By pingoor

更新日期:

文章目录
  1. 1. 概述
  2. 2. 说明
    1. 2.1. name
    2. 2.2. version
    3. 2.3. description
    4. 2.4. keywords
    5. 2.5. homepage
    6. 2.6. bugs
    7. 2.7. license
    8. 2.8. author
    9. 2.9. contributors
    10. 2.10. files
    11. 2.11. MAIN
    12. 2.12. bin
    13. 2.13. man
    14. 2.14. directories
    15. 2.15. repository
    16. 2.16. scripts
    17. 2.17. dependencies
    18. 2.18. devDependencies
    19. 2.19. engines
    20. 2.20. preferGlobal
    21. 2.21. private
    22. 2.22. publishConfig
  3. 3. 参考资料

概述

我们在使用nodejs做web开发或者使用npm管理各种包资源的时候，在包的根目录下一定会有package.json文件。这是因为nodejs采用了CommonJS规范。package.json是CommonJS规定的用来描述包的文件。
严格符合CommonJS规范的包应该具备以下特征: 

1. package.json必须在包的顶层目录下; 
2. 二进制文件应该在bin目录下; 
3. JavaScript代码应该在lib目录下; 
4. 文档应该在doc目录下; 
5. 单元测试应该在test目录下。

nodejs在调用某个包时,会首先检查包中package.json文件的main字段,将其作为包的接口模块,如果package.json或main字段不存在,会尝试寻找index.js或index.node作为包的入口。

说明

符合规范的package.json文件应该含有以下字段。

name

包的名称。name必须设置，且必须是唯一，否则你的包将不会被安装。name的设置一般遵循以下规则：

1. 全部小写；
2. 不要包含"js"或"node"字符；
3. 不要以点号和下划线开头，不使用不符合url字符串格式标准的字符；
4. 要言简意赅；
5. 如果你的包需要发布，则要保证name在npm注册表中。

version

包的版本。version必须设置。name和version组合构成你的包的唯一标识。版本号遵循 MAJOR.MINOR.PATCH 的编写规则。

1. MAJOR 主版本。当包有重大修改时应该改变。
2. MINIR 小版本。当包进行了一些功能性修改时应该改变。
3. PATH 补丁。当包或进行了bug修复后应该修改。

description

包的描述信息。应该言简意赅。

keywords

包的关键词。应该是一个集合。

homepage

项目主页的url地址。
注意： homepage不同于url。如果在package.json中设置了url字段，npm注册表会认为包被重定向到其他的发布位置，这样的话你会被鄙视的。所以不推荐使用url字段。

bugs

bug提交的url地址或者email邮箱。
例如：

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

license

包的许可。一些通用的许可如 MIT 或 BSD-3-Clause。更多许可请参见 SPDX License List
例如：

"license": "MIT"

author

包的作者。包括作者的姓名，也可添加email和个人主页信息。
例如：

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

或者简写成：

"Barney Rubble <b@rubble.com> (http://barnyrubble.tumblr.com/)"

contributors

包的参与者。应该是一个集合。内容与author字段相同。

files

包含到包中的文件。应该是一个集合。可以在包的根目录下提供了一个”.npmignore”文件，指定不被包包含的文件。

MAIN

指向包的主入口。例如，如果你的包名为 foo，当用户通过 require('foo') 访问包时，就会返回你的主模块的exports对象。
例如：

"main": "lib/foo.js"

注： main在markdown中做标题时会导致后面的部分文字格式错误，故这里将main写成大写的MAIN。

bin

用于对外暴露包中的可执行脚本文件。应该是一个hash对象。对象的key应该是可执行脚本的名字，value应该是指向可执行脚本文件的相对路径。包安装时会自动安装这些可执行脚本路径到环境变量PATH中。
例如：

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

如果只有一个可执行脚本文件，也可简写成：

"bin": "./path/to/program"

man

指示帮助文档的位置。可以是单个或多个文件。
单文件示例：

"man" : "./man/doc.1"

多文件示例：

"man" : [ "./man/foo.1", "./man/bar.1" ]

directories

显示包的组织结构。

directories.lib: 指示库的位置。
directories.bin：意义同bin字段；如果已经设置过bin字段，则这里的bin无效。
directories.man：意义同man字段。
directories.doc：放置markdown文件的位置。
directories.example： 放置样例脚本文件的位置。

例如：

"directories":{"doc":"./doc","man":"./man","lib":"./lib","bin":"./bin"}

repository

指示包的源代码存储的位置和类型。可以帮助其他想贡献代码的人。
例如存储到github上：

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

或者存放到svn上：

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

scripts

对外暴露额外的npm命令。应该是一个hash对象。对象的key是npm命令，value是脚本或脚本的路径。这些命令可以通过 npm run {command name} 或 npm run-script {command name} 来执行这些命令。
例如：

 "script": {
    "test": "vows --spec --isolate",
    "start": "node index.js",
    "predeploy": "echo im about to deploy",
    "postdeploy": "echo ive deployed",
    "prepublish": "coffee --bare --compile --output lib/foo src/foo/*.coffee"
  }

dependencies

包依赖的其他包。当按照包时，依赖的包会一起被安装。是一个包含包名和版本范围的hash对象。
版本范围的规则如下：

  • version 必须与指定的版本号完全匹配
  • >version 必须高于指定的版本号
  • >=version 必须高于或等于指定的版本号
  • <version 必须小于指定的版本号
  • <=version 必须小于或等于指定的版本号
  • ~version 必须与指定的版本号趋近。如 ~1.2.3 := >=1.2.3 <1.3.0
  • ^version 必须与指定版本号匹配。如 ^1.2.3 := >=1.2.3 <2.0.0
  • 1.2.x 等价于 >=1.2.0 <1.3.0
  • * 匹配任何版本
  • "" 空字符，等价于*
  • version1 - version2 等价于 >=version1 <=version2
  • range1 || range2 range1 或 range2 范围内的版本都可以
  • github... 从git上获取指定版本
  • user/repo 从github上获取指定版本
  • http://... 从url地址获取指定版本

更多规则可以参见 npm版本语义。

例如：

"dependencies": {
    "primus": "*",
    "async": "~0.8.0",
    "express": "4.2.x",
    "winston": "git://github.com/flatiron/winston#master",
    "bigpipe": "bigpipe/pagelet",
    "plates": "https://github.com/flatiron/plates/tarball/master"
  }

devDependencies

开发或测试时的包依赖。不用安装其他额外的文档。可以使用 npm install --dev 来安装。设置规则与dependencies字段一样。

engines

指定node的版本。版本的设置规则同dependencies字段。
例如：

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

preferGlobal

指示包应该在全局安装。安装命名为 npm install -g {module-name}。
例如：

"preferGlobal": true

private

指示包不应该被发布。
例如：

"private": true

publishConfig

包发布时的配置参数。这些配置参数会覆盖默认的npm配置。最常见的用法是使用publishConfig来发布你的包到私有npm注册表，这样既能利用npm提供的服务，又可以私有你的包。

参考资料

  1. Specifics of npm’s package.json handling

  2. Nodejitsu package.json guide

文章目录
  1. 1. 概述
  2. 2. 说明
    1. 2.1. name
    2. 2.2. version
    3. 2.3. description
    4. 2.4. keywords
    5. 2.5. homepage
    6. 2.6. bugs
    7. 2.7. license
    8. 2.8. author
    9. 2.9. contributors
    10. 2.10. files
    11. 2.11. MAIN
    12. 2.12. bin
    13. 2.13. man
    14. 2.14. directories
    15. 2.15. repository
    16. 2.16. scripts
    17. 2.17. dependencies
    18. 2.18. devDependencies
    19. 2.19. engines
    20. 2.20. preferGlobal
    21. 2.21. private
    22. 2.22. publishConfig
  3. 3. 参考资料