文件 package.json 的说明文档

文档复制 yarnpkg 官方文档，并非彻底复制，增长了一些内容和一些描述，做为笔记存储。你也能够参考 npm documentation, std-pkg, clean-publish, package-json-validator, cosmiconfig, rc。

欢迎来点 Star： github.com/jaywcjlove/…

重要字段

你的 package.json 中最重要的两个字段是 name 和 version，若是没有它们，您的包将没法安装。 name 和version 字段一块儿用于建立惟一ID。

name

{
  "name": "my-awesome-package"
}
复制代码

这是您的 包 的名称。 它在URL中使用，做为参数命令行，以及 node_modules 中的目录名。

yarn add [包名]
# or
npm install [包名]
复制代码

node_modules/[包名]
复制代码

https://registry.npmjs.org/[包名]/-/[包名]-[version].tgz
复制代码

规则

• 必须小于或等于214个字符（包括 @scope/ for 范围包）。
• 不能以点（.）或下划线（_）开头。
• 名称中不得包含大写字母。
• 必须仅使用URL安全字符。

Tips

• 不要使用和 Node.js 核心模块相同的名字。
• 不要在名字里包含 js 或者 node 单词。
• 短小精悍，让人看到名字就大概了解包的功能，记住它也会被用在 require() 调用里。
• 保证名字在 npm registry 里是惟一的。

version

包的当前版本，严格遵循 Semantic Versioning 2.0.0 语义化版本规范。

{
  "version": "1.0.0"
}
复制代码

信息类字段

description

Description 是帮助使用者了解包的功能的字符串，包管理器也会把这个字符串做为搜索关键词。

{
  "description": "个人包的概要简短描述"
}
复制代码

keywords

关键字是一个字符串数组，当在包管理器里搜索包时颇有用。

{
  "keywords": ["short", "relevant", "keywords", "for", "searching"]
}
复制代码

license

全部包都应该指定许可证，以便让用户了解他们是在什么受权下使用此包，以及此包还有哪些附加限制。

{
  "license": "MIT",
  "license": "(MIT or GPL-3.0)",
  "license": "SEE LICENSE IN LICENSE_FILENAME.txt",
  "license": "UNLICENSED"
}
复制代码

鼓励使用开源 (OSI-approved) 许可证，除非你有特别的缘由不用它。 若是你开发的包是你工做的一部分，最好和公司讨论后再作决定。

license字段必须是如下之一:

• 若是你使用标准的许可证，须要一个有效地 SPDX 许可证标识。
• 若是你用多种标准许可证，须要有效的 SPDX 许可证表达式2.0语法表达式。
• 若是你使用非标准的许可证，一个 SEE LICENSE IN <文件名> 字符串指向你的包里顶级目录的一个 <文件名>。
• 若是你不想在任何条款下受权其余人使用你的私有或未公开的包，一个 UNLICENSED 字符串。

连接类字段

各类指向项目文档、issues 上报，以及代码托管网站的连接字段。

homepage

是包的项目主页或者文档首页。

{
  "homepage": "https://your-package.org"
}
复制代码

bugs

问题反馈系统的 URL，或者是 email 地址之类的连接。用户经过该途径向你反馈问题。

{
  "bugs": "https://github.com/user/repo/issues"
}
复制代码

repository

是代码托管的位置。

{
  "repository": { "type": "git", "url": "https://github.com/user/repo.git" },
  "repository": "github:user/repo",
  "repository": "gitlab:user/repo",
  "repository": "bitbucket:user/repo",
  "repository": "gist:a1b2c3d4e5f"
}
复制代码

The repository is the location where the actual code for your package lives.

项目维护类字段

项目的维护者。

author

做者信息，一我的。

{
  "author": { "name": "Your Name", "email": "you@example.com", "url": "http://your-website.com" },
  "author": "Your Name <you@example.com> (http://your-website.com)"
}
复制代码

contributors

贡献者信息，可能不少人。

{
  "contributors": [
    { "name": "Your Friend", "email": "friend@example.com", "url": "http://friends-website.com" }
    { "name": "Other Friend", "email": "other@example.com", "url": "http://other-website.com" }
  ],
  "contributors": [
    "Your Friend <friend@example.com> (http://friends-website.com)",
    "Other Friend <other@example.com> (http://other-website.com)"
  ]
}
复制代码

文件类信息

指定包含在项目中的文件，以及项目的入口文件。

files

{
  "files": [
    "filename.js",
    "directory/",
    "glob/*.{js,json}"
  ]
}
复制代码

项目包含的文件，能够是单独的文件、整个文件夹，或者通配符匹配到的文件。

main

项目的入口文件。

{
  "main": "filename.js"
}
复制代码

bin

随着项目一块儿被安装的可执行文件。

{
  "bin": "bin.js",
  "bin": {
    "命令名称": "bin/命令路径/命令名称.js",
    "other-command": "bin/other-command"
  }
}
复制代码

man

项目的入口文件。

{
  "man": "./man/doc.1",
  "man": ["./man/doc.1", "./man/doc.2"]
}
复制代码

directories

{
  "directories": {
    "lib": "path/to/lib/",
    "bin": "path/to/bin/",
    "man": "path/to/man/",
    "doc": "path/to/doc/",
    "example": "path/to/example/"
  }
}
复制代码

当你的包安装时，你能够指定确切的位置来放二进制文件、man pages、文档、例子等。

types

这是一个只在 TypeScript 中生效的字段，若是您的包有一个 main.js 文件，您还须要在 package.json 文件中指明主声明文件。 将 types 属性设置为指向 bundled 的声明文件。 例如：

{
  "types": "./lib/main.d.ts",
}
复制代码

若是您的主声明文件名为 index.d.ts 而且位于包的根目录（index.js旁边），则不须要标记 types 属性，建议这样作。

打包包字段

module

pkg.module 将指向具备 ES2015 模块语法的模块，但仅指向目标环境支持的语法功能。 完整的描述在这里。

支持：rollup, webpack

browser

字段由模块做者提供，做为 JavaScript 包或组件工具的提示，用于打包模块以供客户端使用。 提案就在这里。

esnext

完整的提案在这里。 简短说明：

• esnext：ES模块中使用阶段4功能（或更旧版本）的源代码，未编译。
• main：指向一个CommonJS模块（或UMD模块），其 JavaScript 与 Node.js 当前能够处理的同样现代。
• 大多数 module 用例应该能够经过 esnext 处理。
• browser 能够经过 esnext 的扩展版原本处理

{
  "main": "main.js",
  "esnext": {
    "main": "main-esnext.js",
    "browser": "browser-specific-main-esnext.js"
  }
}
复制代码

另请参阅：Delivering untranspiled source code via npm

任务类字段

包里还能够包含一些可执行脚本或者其余配置信息。

scripts

{
  "scripts": {
    "build-project": "node build-project.js"
  }
}
复制代码

脚本是定义自动化开发相关任务的好方法，好比使用一些简单的构建过程或开发工具。 在 scripts 字段里定义的脚本，能够经过 yarn run <script> 命令来执行。 例如，上述 build-project 脚本能够经过 yarn run build-project 调用，并执行 node build-project.js。

有一些特殊的脚本名称。 若是定义了 preinstall 脚本，它会在包安装前被调用。 出于兼容性考虑，install、postinstall 和 prepublish 脚本会在包完成安装后被调用。

start 脚本的默认值为 node server.js。

参考文档：npm docs

特定的 scripts

对于如下脚本，npm 支持 package.json 文件的 scripts 默认命令字段：

• prepublish: 在打包并发布包以前运行，以及在没有任何参数的本地 npm 安装以前运行。 （见下文）
• prepare: 在打包和发布包以前运行，在没有任何参数的本地 npm install 上运行，以及安装 git 依赖项时（见下文）。 这是在 preublish 以后运行，可是在 preublishOnly 以前运行。
• prepublishOnly: 在包准备和打包以前运行，仅限于npm发布。 （见下文。）
• prepack: 在打包 tarball 以前运行（在 npm pack，npm publish，以及安装 git 依赖项时）
• postpack: 在生成 tarball 以后运行并移动到其最终目标。
• publish, postpublish: 在包发布后运行。
• preinstall: 在安装软件包以前运行。
• install, postinstall: 安装包后运行。
• preuninstall, uninstall: 在卸载软件包以前运行。
• postuninstall: 在卸载软件包以后运行。
• preversion: 在改变包版本以前运行。
• version: 改变包版本后运行，但提交以前。
• postversion: 改变包版本后运行，而后提交。
• pretest, test, posttest: 由 npm test 命令运行。
• prestop, stop, poststop: 由 npm stop 命令运行。
• prestart, start, poststart: 由 npm start 命令运行。
• prerestart, restart, postrestart: 由 npm restart 命令运行。 注意：若是没有提供重启脚本，npm restart 将运行 stop 和start 脚本。
• preshrinkwrap, shrinkwrap, postshrinkwrap: 由 npm shrinkwrap 命令运行。

参考文档：npm docs.

config

{
  "config": {
    "port": "8080"
  }
}
复制代码

配置你的脚本的选项或参数。

依赖描述类字段

你的包极可能依赖其余包。你能够在你的 package.json 文件里指定那些依赖。

dependencies

这些是你的包的开发版和发布版都须要的依赖。

{
  "dependencies": {
    "package-1": "^3.1.4",
    "package-2": "file:./path/to/dir"
  }
}
复制代码

你能够指定一个确切的版本、一个最小的版本 (好比 >=) 或者一个版本范围 (好比 >= ... <)。
包也能够指向本地的一个目录文件夹。

devDependencies

这些是只在你的包开发期间须要，可是生产环境不会被安装的包。

{
  "devDependencies": {
    "package-2": "^0.4.2"
  }
}
复制代码

peerDependencies

平行依赖容许你说明你的包和其余包版本的兼容性。

{
  "peerDependencies": {
    "package-3": "^2.7.18"
  }
}
复制代码

optionalDependencies

可选依赖能够用于你的包，但不是必需的。若是可选包没有找到，安装还能够继续。

{
  "optionalDependencies": {
    "package-5": "^1.6.1"
  }
}
复制代码

bundledDependencies

打包依赖是发布你的包时将会一块儿打包的一个包名数组。

{
  "bundledDependencies": [
    "package-4"
  ]
}
复制代码

系统

你能够提供和你的包关联的系统级的信息，好比操做系统兼容性之类。

engines

指定使用你的包客户必须使用的版本，这将检查 process.versions 以及当前 yarn 版本。

{
  "engines": {
    "node": ">=4.4.7 <7.0.0",
    "zlib": "^1.2.8",
    "yarn": "^0.14.0"
  }
}
复制代码

此检查遵照正常的 semver 规则，但有一个例外。 它容许预发布版本匹配未明确指定预发布的 semver。 例如，1.4.0-rc.0 匹配 >=1.3.0，但它与典型的 semver 检查不匹配。

os

此选项指定你的包的操做系统兼容性，它会检查 process.platform。

{
  "os": ["darwin", "linux"],
  "os": ["!win32"]
}
复制代码

cpu

使用这个选项指定你的包将只能在某些 CPU 体系架构上运行，这会检查 process.arch。

{
  "cpu": ["x64", "ia32"],
  "cpu": ["!arm", "!mips"]
}
复制代码

发布

private

{
  "private": true
}
复制代码

若是你不想你的包发布到包管理器(npm 或者 私有包管理)，设置为 true。

publishConfig

这些配置值将在你的包发布时使用。好比，你能够给包打标签。

{
  "publishConfig": {
    "registry": "https://registry.npm.taobao.org"
  }
}
复制代码

这是一组将在发布时使用的配置值。 若是要设置标记，注册表或访问权限，则特别方便，以便确保给定的包未标记为 latest，发布到全局公共 registry 或默认状况下，做用域模块(@scoped)是私有的。

能够覆盖任何配置值，但只有 tag，registry 和 access 可能对于发布而言很重要，npm-config。

Yarn

flat

若是你的包只容许给定依赖的一个版本，你想强制和命令行上 yarn install --flat 相同的行为，把这个值设为 true。

{
  "flat": true
}
复制代码

请注意，若是你的 package.json 包含 "flat": true 而且其它包依赖你的包 (好比你在构建一个库，而不是应用)， 其它那些包也须要在它们的 package.json 加上 "flat": true，或者在命令行上用 yarn install --flat 安装。

resolutions

{
  "resolutions": {
    "transitive-package-1": "0.0.29",
    "transitive-package-2": "file:./local-forks/transitive-package-2",
    "dependencies-package-1/transitive-package-3": "^2.1.1"
  }
}
复制代码

容许您覆盖特定嵌套依赖项的版本。 有关完整规范，请参见选择性版本解析 RFC。

注意，yarn install --flat 命令将会自动在 package.json 文件里加入 resolutions 字段。