package.json

原文链接:http://www.mujiang.info/translation/npmjs/files/package.json.html

DESCRIPTION

本文档有所有package.json中必要的配置。它必须是真正的json,而不是js对象。
本文档中描述的很多行为都受npm-config(7)的影响。

一、name

在package.json中 最重要 的就是name和version字段。
他们都是必须的,如果没有就无法install。
name和version一起组成的标识在假设中是唯一的。
改变包应该同时改变version。
name是这个东西的名字。

注意:不要把node或者js放在名字中。因为你写了package.json它就被假定成为了js,不过你可以用"engine"字段指定一个引擎(见后文)。

这个名字会作为在URL的一部分、命令行的参数或者文件夹的名字。任何non-url-safe的字符都是不能用的。

这个名字可能会作为参数被传入require(),所以它应该比较短,但也要意义清晰。

在命名你的name之前,你可能要去npm registry查看一下这个名字是否已经被使用了。 http://registry.npmjs.org/

二、version

version必须能被 node-semver解析,它被包在npm的依赖中。(要自己用可以执行npm install semver)
更多可用的“数字”或者“范围”见semver(7).

三、scripts

存放 npm脚本的地方,npm run XXX,键值对形式存在

image.png

参见 npm-scripts(7)

四、dependencies

你的项目依赖的其他的第三方包。

请不要将测试或过渡性的依赖放在dependencies中。
见下文的devDependencies

1、波浪符号(~):更新到当前minor version(也就是中间的那位数字)中最新的版本。

body-parser:~1.15.2 --> 1.15.X ,但不会更新到: 1.16.0

2、插入符号(^):更新到当前major version(也就是第一位数字)中最新的版本。

bluebird:^3.3.4 --> 3.X.X, 但不会自动更新到4.0.0。

比如下面都是合法的:

{ 
 "devDependencies": {
    "acorn": "~0.6.0",
    "baconjs": "^0.7.43",
    "bluebird": "^2.9.2",
    "body-parser": "^1.10.2",
    "browserify": "^8.1.1",
    "cli-table": "~0.3.1",
    "co": "^4.2.0",
  }
}

五、devDependencies

仅在开发环境下使用的依赖包,放在devDependencies中。

线上发布时,如果dev依赖中的包不需要,那么可以执行:
npm prune --production 来删除已安装的dev依赖包,以减少项目体积。

对于构建步骤,比如需要编译CoffeeScript,可以用prepublish脚本去实现,并把它依赖的包放在devDependency中。
比如:

{ 
  "name": "ethopia-waza", 
  "description": "a delightfully fruity coffee varietal", 
  "version": "1.2.3", 
  "devDependencies": { 
    "coffee-script": "~1.6.3" 
  }, 
  "scripts": { 
    "prepublish": "coffee -o lib/ -c src/waza.coffee" 
  }, 
  "main": "lib/waza.js"
}

六、optionalDependencies

如果一个依赖可用,但你希望在它安装错误的时候npm也能继续初始化,那么你可以把它放在optionalDependencieshash中。

线上发布时可以选择不安装此目录下的依赖:
npm install --no-optional

处理缺乏依赖也是你的程序的责任。比如像这样:

try { 
  var foo = require('foo') 
  var fooVersion = require('foo/package.json').version
} catch (er) { 
  foo = null
}
if ( notGoodFooVersion(fooVersion) ) { 
  foo = null
}
// .. then later in your program ..
if (foo) { 
  foo.doFooThings()
}

optionalDependencies会覆盖dependencies中同名的项,所以通常比只放在一个地方好。

七、bundledDependencies

一组包名,他们会在发布的时候被打包进去。
拼成"bundleDependencies"
(缺d)也可以。

八、keywords

放简介,字符串。方便在 npm search中搜索。

九、homepage

一般放这个项目的 git地址

十、bugs

你项目的提交问题的url和(或)邮件地址。

{ 
  "url" : "http://github.com/owner/project/issues", 
  "email" : "project@hostname.com"
}

你可以指定一个或者两个。如果你只想提供一个url,那就直接用字符串。
如果提供了url,它会被npm bugs命令使用。

十一、license

你应该要指定一个许可证,让人知道使用的权利和限制的。
最简单的方法是,假如你用一个像BSD或者MIT这样通用的许可证,就只需要指定一个许可证的名字,像这样:

{ "license" : "BSD" }

如果你有更复杂的许可条件,或者想要提供给更多地细节,可以这样:

"licenses" : [ 
   { 
       "type" : "MyLicense" , 
       "url" : "http://github.com/owner/project/path/to/license" 
   }
]

在根目录中提供一个许可证文件也蛮好的。
people fields: author, contributors
author是一个人。contributors是一堆人的数组。person是一个有name字段,可选的有url、email字段的对象,像这样:

{ 
  "name" : "Barney Rubble", 
  "email" : "b@rubble.com", 
  "url" : "http://barnyrubble.tumblr.com/"
}

或者可以把所有的东西都放到一个字符串里,npm会给你解析:
"Barney Rubble b@rubble.com (http://barnyrubble.tumblr.com/)

email和url在两种形式中都是可选的。
也可以在你的npm用户信息中设置一个顶级的maintainers字段。

十二、files

files是一个包含项目中的文件的数组。如果命名了一个文件夹,那也会包含文件夹中的文件。(除非被其他条件忽略了)
你也可以提供一个.npmignore文件,让即使被包含在files字段中得文件被留下。其实就像.gitignore一样。

image.png

十三、main

main字段配置一个文件名指向模块的入口程序。如果你包的名字叫foo,然后用户require("foo"),main配置的模块的exports对象会被返回。
这应该是一个相对于根目录的文件路径。

十四、bin

很多包都有一个或多个可执行的文件希望被放到PATH中。npm让妈妈再也不用担心了(实际上,就是这个功能让npm可执行的)。
要用这个功能,给package.json中的bin
字段一个命令名到文件位置的map。初始化的时候npm会将他链接到prefix/bin
(全局初始化)或者./node_modules/.bin/
(本地初始化)。
比如,npm有:

{ "bin" : { "npm" : "./cli.js" } }

所以,当你初始化npm,它会创建一个符号链接到cli.js
脚本到/usr/local/bin/npm。
如果你只有一个可执行文件,并且名字和包名一样。那么你可以只用一个字符串,比如:

{ "name": "my-program", "version": "1.2.5", "bin": "./path/to/program" }

结果和这个一样:

{ "name": "my-program", "version": "1.2.5", "bin" : { "my-program" : "./path/to/program" } }

十五、man

指定一个单一的文件或者一个文件数组供man程序使用。
如果只提供一个单一的文件,那么它初始化后就是man <pkgname>
的结果,而不管实际的文件名是神马,比如:

{ 
  "name" : "foo", 
  "version" : "1.2.3", 
  "description" : "A packaged foo fooer for fooing foos", 
  "main" : "foo.js", 
  "man" : "./man/doc.1"
 }

这样man foo就可以用到./man/doc.1文件了。
如果文件名不是以包名开头,那么它会被冠以前缀,下面的:

{ 
  "name" : "foo",
  "version" : "1.2.3", 
  "description" : "A packaged foo fooer for fooing foos", 
  "main" : "foo.js", 
  "man" : [ "./man/foo.1", "./man/bar.1" ]
 }

会为man foo和man foo-bar创建文件。
man文件需要以数字结束,然后可选地压缩后以.gz为后缀。The number dictates which man section the file is installed into.

{ 
  "name" : "foo", 
  "version" : "1.2.3", 
  "description" : "A packaged foo fooer for fooing foos", 
  "main" : "foo.js", 
  "man" : [ "./man/foo.1", "./man/foo.2" ]
}

会为man foo和man 2 foo创建。

directories

CommonJS Packages规范说明了几种方式让你可以用directories
hash标示出包得结构。如果看一下npm's package.json,你会看到有directories标示出doc, lib, and man。
在未来,这个信息可能会被用到。

directories.lib

告诉屌丝们你的库文件夹在哪里。目前没有什么特别的东西需要用到lib文件夹,但确实是重要的元信息。

directories.bin

如果你指定一个“bin”目录,然后在那个文件夹中得所有文件都会被当做"bin"字段使用。
如果你已经指定了“bin”字段,那这个就无效。

directories.man

一个放满man页面的文件夹。贴心地创建一个“man”字段。A folder that is full of man pages. Sugar to generate a "man" array bywalking the folder.

directories.doc

将markdown文件放在这里。最后,这些会被很好地展示出来,也许,某一天。Put markdown files in here. Eventually, these will be displayed nicely,maybe, someday.

directories.example

将事例脚本放在这里。某一天,它可能会以聪明的方式展示出来。

repository

指定你的代码存放的地方。这个对希望贡献的人有帮助。如果git仓库在github上,那么npm docs
命令能找到你。
这样做:

"repository" : { 
  "type" : "git" , 
  "url" : "http://github.com/isaacs/npm.git" 
}

"repository" : { 
  "type" : "svn" , 
  "url" : "http://v8.googlecode.com/svn/trunk/" 
}

URL应该是公开的(即便是只读的)能直接被未经过修改的版本控制程序处理的url。不应该是一个html的项目页面。因为它是给计算机看的。

config

"config" hash可以用来配置用于包脚本中的跨版本参数。在实例中,如果一个包有下面的配置:

{ "name" : "foo", "config" : { "port" : "8080" } }

然后有一个“start”命令引用了npm_package_config_port
环境变量,用户可以通过npm config set foo:port 8001
来重写他。
参见 npm-config(7)npm-scripts(7)

engines

你可以指定工作的node的版本:

{ "engines" : { "node" : ">=0.10.3 <0.12" } }

并且,像dependensies一样,如果你不指定版本或者指定“*”作为版本,那么所有版本的node都可以。
如果指定一个“engines”字段,那么npm会需要node在里面,如果“engines”被省略,npm会假定它在node上工作。
你也可以用“engines”字段来指定哪一个npm版本能更好地初始化你的程序,如:

{ "engines" : { "npm" : "~1.0.20" } }

记住,除非用户设置engine-strict标记,这个字段只是建议值。

  • engineStrict

如果你确定你的模块一定不会运行在你指定版本之外的node或者npm上,你可以在package.json文件中设置"engineStrict":true。它会重写用户的engine-strict
设置。
除非你非常非常确定,否则不要这样做。如果你的engines hash过度地限制,很可能轻易让自己陷入窘境。慎重地考虑这个选择。如果大家滥用它,它会再以后的npm版本中被删除。

  • os

你可以指定你的模块要运行在哪些操作系统中:
"os" : [ "darwin", "linux" ]

你也可以用黑名单代替白名单,在名字前面加上“!”就可以了:
"os" : [ "!win32" ]

操作系统用process.platform来探测。
虽然没有很好地理由,但它是同时支持黑名单和白名单的。

  • cpu

如果你的代码只能运行在特定的cpu架构下,你可以指定一个:
"cpu" : [ "x64", "ia32" ]

就像os选项,你也可以黑一个架构:
"cpu" : [ "!arm", "!mips" ]

cpu架构用process.arch探测。

  • preferGlobal

如果包主要是需要全局安装的命令行程序,就设置它为true
来提供一个warning给只在局部安装的人。
它不会真正的防止用户在局部安装,但如果它没有按预期工作它会帮助防止产生误会。

  • private

如果你设置 "private": true,npm就不会发布它。
这是一个防止意外发布私有库的方式。如果你要确定给定的包是只发布在特定registry(如内部registry)的,用publishConfig hash的描述来重写registry的publish-time配置参数。

  • publishConfig

这是一个在publish-time使用的配置集合。当你想设置tag或者registry的时候它非常有用,所以你可以确定一个给定的包没有打上“lastest”的tag或者被默认发布到全局的公开registry。
任何配置都可以被重写,但当然可能只有“tag”和“registry”与发布的意图有关。
参见npm-config(7)有可以被重写的列表。

  • DEFAULT VALUES

npm会根据包的内容设置一些默认值。
"scripts": {"start": "node server.js"}

如果包的根目录有server.js文件,npm会默认将start命令设置为node server.js。

"scripts":{"preinstall": "node-waf clean || true; node-waf configure build"}

如果包的根目录有wscript文件,npm会默认将preinstall命令用node-waf进行编译。

"scripts":{"preinstall": "node-gyp rebuild"} 

如果包的根目录有binding.gyp文件,npm会默认将preinstall命令用node-gyp进行编译。

"contributors": [...]

如果有AUTHORS
文件,npm会默认逐行按Name <email> (url)格式处理,邮箱和url是可选的。#号和空格开头的行会被忽略。

SEE ALSO
semver(7)
npm-init(1)
npm-version(1)
npm-config(1)
npm-config(7)
npm-help(1)
npm-faq(7)
npm-install(1)
npm-publish(1)
npm-rm(1)

最后编辑于
©著作权归作者所有,转载或内容合作请联系作者
  • 序言:七十年代末,一起剥皮案震惊了整个滨河市,随后出现的几起案子,更是在滨河造成了极大的恐慌,老刑警刘岩,带你破解...
    沈念sama阅读 151,829评论 1 331
  • 序言:滨河连续发生了三起死亡事件,死亡现场离奇诡异,居然都是意外死亡,警方通过查阅死者的电脑和手机,发现死者居然都...
    沈念sama阅读 64,603评论 1 273
  • 文/潘晓璐 我一进店门,熙熙楼的掌柜王于贵愁眉苦脸地迎上来,“玉大人,你说我怎么就摊上这事。” “怎么了?”我有些...
    开封第一讲书人阅读 101,846评论 0 226
  • 文/不坏的土叔 我叫张陵,是天一观的道长。 经常有香客问我,道长,这世上最难降的妖魔是什么? 我笑而不...
    开封第一讲书人阅读 42,600评论 0 191
  • 正文 为了忘掉前任,我火速办了婚礼,结果婚礼上,老公的妹妹穿的比我还像新娘。我一直安慰自己,他们只是感情好,可当我...
    茶点故事阅读 50,780评论 3 272
  • 文/花漫 我一把揭开白布。 她就那样静静地躺着,像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上,一...
    开封第一讲书人阅读 39,695评论 1 192
  • 那天,我揣着相机与录音,去河边找鬼。 笑死,一个胖子当着我的面吹牛,可吹牛的内容都是我干的。 我是一名探鬼主播,决...
    沈念sama阅读 31,136评论 2 293
  • 文/苍兰香墨 我猛地睁开眼,长吁一口气:“原来是场噩梦啊……” “哼!你这毒妇竟也来了?” 一声冷哼从身侧响起,我...
    开封第一讲书人阅读 29,862评论 0 182
  • 序言:老挝万荣一对情侣失踪,失踪者是张志新(化名)和其女友刘颖,没想到半个月后,有当地人在树林里发现了一具尸体,经...
    沈念sama阅读 33,453评论 0 229
  • 正文 独居荒郊野岭守林人离奇死亡,尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 29,942评论 2 233
  • 正文 我和宋清朗相恋三年,在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 31,347评论 1 242
  • 序言:一个原本活蹦乱跳的男人离奇死亡,死状恐怖,灵堂内的尸体忽然破棺而出,到底是诈尸还是另有隐情,我是刑警宁泽,带...
    沈念sama阅读 27,790评论 2 236
  • 正文 年R本政府宣布,位于F岛的核电站,受9级特大地震影响,放射性物质发生泄漏。R本人自食恶果不足惜,却给世界环境...
    茶点故事阅读 32,293评论 3 221
  • 文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹,春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 25,839评论 0 8
  • 文/苍兰香墨 我抬头看了看天上的太阳。三九已至,却和暖如春,着一层夹袄步出监牢的瞬间,已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 26,448评论 0 181
  • 我被黑心中介骗来泰国打工, 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留,地道东北人。 一个月前我还...
    沈念sama阅读 34,564评论 2 249
  • 正文 我出身青楼,却偏偏与公主长得像,于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子,可洞房花烛夜当晚...
    茶点故事阅读 34,623评论 2 249

推荐阅读更多精彩内容

  • Spring Cloud为开发人员提供了快速构建分布式系统中一些常见模式的工具(例如配置管理,服务发现,断路器,智...
    卡卡罗2017阅读 134,050评论 18 139
  • 原文:http://javascript.ruanyifeng.com/nodejs/packagejson.ht...
    水墨熊猫阅读 1,105评论 0 2
  • name 必须字段。提示: 不要在name中包含 js、 node 字样; 这个名字最终会是 URL 的一部分,命...
    djyuning阅读 1,363评论 0 1
  • 1.背景介绍 NPM是什么?NPM(node package manager),通常称为node包管理器。顾名思义...
    我叫于搞吧阅读 1,097评论 0 1
  • 作为一个前端工程师,不断地去学习前端新技术是必须的。在这过程中,不断接触开源项目是必不可少的。github上的开源...
    居客侠阅读 1,101评论 0 0