文件描述
package.json 文件是项目的清单, 可以做很多完全互不相关的事情, 必须是 json 文件格式, 而不仅仅是 Javascript 对象文字, 其中包含名称,描述和版本之类的信息以及配置在发布属于自己的包时下载安装的指定文件(files)等, 其中带有 * 标识的为必填项
可读元数据
*name
npm包名称, 在发布时必须要包含的元数据, 和版本(version)共同构成一个唯一的标识符, 可用于在 npm search, 包含以下几种规则
- 必须小于或等于214个字符
- 不能包含空格, 连接符(-)或下划线 且必须全部小写
- 不能包含任何非 URL安全字符
一些技巧
- 不使用与核心节点模块相同的名称
- 不要在名称中加入 js 或 node
- 名称应该相对简短
*version
**指定软件包的当前版本, 遵循版本的语义版本控制记法, 意思就是以3个数字表示, 如 1.1.1,以及在安装时指定的版本区别, 且必须可由 node-semver 解析 通过 npm init 初始化时的默认版本为 1.0.0, 不同位置的数字表示的含义不同, 参考 **semver 描述
- 第一个数字表示主版本号, 通常用于重大更改时使用, 不兼容的 API 修改
- 第二个数字表示次版本号, 向下兼容的功能性新增
- 第三个数字表示补丁版本号, 向下兼容的问题修正
- 主版本号为0(0.y.z)的软件包处于开发初始阶段, 随时都有可能被修改,默认为不稳定版本
同时版本号中可包含 alpha(产品的一个版本, 但没有文档) 和 beta(测试版, 且已包含文档) 可参考 或 what is difference between an alpha and a beta release, 若同时发布了多个版本时, 在安装时需要注意的是版本的优先级
description
用于简单描述软件包的功能, 以及在 npmjs 网站中搜索时匹配到的软件包, 以及 通过 npm search 搜索
keywords
字符串数组, 帮助在使用 npm search 时更容易找到对应软件包, 如
"keywords": ["server", "express"]
main
作为软件包的入口文件, 一般是 index.js, 可以自行修改
人员信息
一般可以有 author 和 contributors 两个字段表示, 通常是以人员的 name email url 组成, author 通常是一个, 而 contributors(贡献者)可包含多个, 有两种方式: 字符形式 和 对象形式, 且 email 和 url 都是可选的
- 字符形式
"author": "name email url",
"contributors": ["name email url"]
- 对象形式
"author": {
"name": "name",
"email": "email",
"url": "url"
},
"contributors": [{
"name": "name",
"email": "email",
"url": "url"
}]
repository
指定仓库地址, 有两种方式: 字符串 和 对象, 常用的为 github 前缀(服务器厂商)还包含有其他的比如 gitlab, type 为代码版本管理工具有 git 和 svn
// 字符串
"repository": "github:nodejscn/node-api-cn"
// 对象
"repository": {
"type": "git",
"url": "https://github.com/nodejscn/node-api-cn.git"
}
dependencies
是以包名作为键 和 版本或版本范围作为值的对象, 表示了项目中所依赖的包, 当下载安装当前包时将会下载到 node_modules 文件夹中
devDependencies
和 dependencies 类似, 区别就是在于只存在于开发阶段使用, 比如常见的 webpack 等构建工具等, 更多关于依赖包的内容比较多
homepage
**指向项目首页, 可以理解通常指的是更多关于项目的文档网站, 比如 **antd 的 homepage
bugs
项目问题跟踪及进行通知的邮件地址, 如果仅提供 URL地址, 可直接使用字符串,也可使用包含 email 和 url 字段的对象
"bugs": "https://github.com/owner/project/issues",
"bugs": {
"url": "https://github.com/owner/project/issues",
"email": "project@hostname.com"
}
license
项目所遵循的协议许可证, 在发布到 NPM 注册表时非常重要,可能会限制一些开发人员或者组织对软件包的使用, 一般都是使用 MIT 或者 ISC之类的字符串, 可参考
funding
赞助商 有两种方式: 字符串 和 包含 type 和 url 的 对象 或者多个赞助商的数组. 可以通过 npm fund <projectName> 进行查看
{
"funding": {
"type" : "individual",
"url" : "http://example.com/donate"
},
"funding": {
"type" : "patreon",
"url" : "https://www.patreon.com/my-account"
},
"funding": "http://example.com/donate",
"funding": [
{
"type" : "individual",
"url" : "http://example.com/donate"
},
"http://example.com/donateAlso",
{
"type" : "patreon",
"url" : "https://www.patreon.com/my-account"
}
]
}
功能元数据
files
可选字段是一个文件模式数组, 描述当下载作为依赖项安装时需要包含的条目, 文件模式遵循与 .gitignore 类似的语法,无论如何设置都会始终包含和忽略某些文件
包含
- package.json
- README
- CHANGES / CHANGELOG / HISTORY
- LICENSE / LICENCE
- NOTICE
- main 字段对应的文件
忽略的文件
- .git
- CVS
- .svn
- .hg
- .lock-wscript
- .wafpickle-N
- ..swp*
- .DS_Store
- ._*
- .npmrc
- npm-debug.log
- node_modules
- config.gypi
- *.orig
- package-lock.json
scripts
包含了生命周期中不同时间运行的脚本命令, 通过 npm run 运行, 如果是以默认内置支持的一些脚本 key 作为key 时可不添加 run 比如 start, 关于 scripts 的内容比较多, 另开一篇: 理解 scripts 及如何开发一个脚本命令
"scripts": {
"start": "nodemon index.js"
}
browserslist
**如果需要在浏览器中进行使用, 需要设置支持的浏览器列表以及对应版本, 参考 browserslist 或 **中文翻译
engines
bin
安装到 PATH 中的可执行文件, 命令名到本地文件名的映射, 安装后 npm 会将该文件符号链接到 prefix/bin 全局安装或 .node_modules/.bin 本地安装, 有两种方式: 字符串 或 对象
"bin": "./cli.js",
"bin": {
"name": ".cli.js"
}
使用js 开发脚本命令时必须使用 #!/usr/bin/env node 开头, 否则脚本将在没有可执行文件的情况下运行
private
如果设置为 true, 房子应用程序/软件包被意外发布到 npm 上, 当然如果是私有包发布时可能会需要收费, 以及如果以 @开头的包名会被认为是私有包, 需要设置为公开包才会允许发布
// @your-name开头会被认为是发布私有包 通过如下命令开放包
npm publish --access public
另外还包含一些命令特有的配置, 比如 eslintConfig, babel, husky 等
