文档主要来源于 yarnpkg 和 npm 官方文档，并不是完全复制，增加了一些内容和一些描述，作为笔记存储。你也可以参考 npm documentation, std-pkg, clean-publish, cosmiconfig, rc。
Warning
🚧 注意：如果你直接克隆项目，项目名称为 package.json，会导致你其它 node.js 项目可能有问题。
git clone https://github.com/jaywcjlove/package.json.git package-json克隆代码的时候指定文件夹名称 package-json 解决问题。
你的 package.json 中最重要的两个字段是 name 和 version，如果没有它们，您的包将无法安装。 name 和version 字段一起用于创建唯一ID。
{
"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 里是唯一的。
包的当前版本，严格遵循 Semantic Versioning 2.0.0 语义化版本规范。
{
"version": "1.0.0"
}Description 是帮助使用者了解包的功能的字符串，包管理器也会把这个字符串作为搜索关键词。
{
"description": "我的包的概要简短描述"
}关键字是一个字符串数组，当在包管理器里搜索包时很有用。
{
"keywords": ["short", "relevant", "keywords", "for", "searching"]
}所有包都应该指定许可证，以便让用户了解他们是在什么授权下使用此包，以及此包还有哪些附加限制。
{
"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": "https://your-package.org"
}问题反馈系统的 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"
}如果软件包的 package.json 不在根目录下（例如，如果它是 monorepo 的一部分），可以指定它所在的目录：
{
"repository": {
"type": "git",
"url": "git+https://github.com/npm/cli.git",
"directory": "workspaces/libnpmpublish"
}
}项目的维护者。
作者信息，一个人。
{
"author": { "name": "Your Name", "email": "[email protected]", "url": "http://your-website.com" },
"author": "Your Name <[email protected]> (http://your-website.com)"
}贡献者信息，可能很多人。
{
"contributors": [
{ "name": "Your Friend", "email": "[email protected]", "url": "http://friends-website.com" }
{ "name": "Other Friend", "email": "[email protected]", "url": "http://other-website.com" }
],
"contributors": [
"Your Friend <[email protected]> (http://friends-website.com)",
"Other Friend <[email protected]> (http://other-website.com)"
]
}指定包含在项目中的文件，以及项目的入口文件。
{
"files": [
"filename.js",
"directory/",
"glob/*.{js,json}"
]
}项目包含的文件，可以是单独的文件、整个文件夹，或者通配符匹配到的文件。
项目的入口文件。
{
"main": "filename.js"
}随着项目一起被安装的可执行文件。
{
"bin": "bin.js",
"bin": {
"命令名称": "bin/命令路径/命令名称.js",
"other-command": "bin/other-command"
}
}项目的入口文件。
{
"man": "./man/doc.1",
"man": ["./man/doc.1", "./man/doc.2"]
}{
"directories": {
"lib": "path/to/lib/",
"bin": "path/to/bin/",
"man": "path/to/man/",
"doc": "path/to/doc/",
"example": "path/to/example/"
}
}当你的包安装时，你可以指定确切的位置来放二进制文件、man pages、文档、例子等。
这是一个只在 TypeScript 中生效的字段，如果您的包有一个 main.js 文件，您还需要在 package.json 文件中指明主声明文件。 将 types 属性设置为指向 bundled 的声明文件。 例如：
{
"types": "./lib/main.d.ts",
}如果您的主声明文件名为 index.d.ts 并且位于包的根目录（index.js旁边），则不需要标记 types 属性，建议这样做。
pkg.module 将指向具有 ES2015 模块语法的模块，但仅指向目标环境支持的语法功能。 完整的描述在这里。
字段由模块作者提供，作为 JavaScript 包或组件工具的提示，用于打包模块以供客户端使用。 提案就在这里。
完整的提案在这里。 简短说明：
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": {
"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
对于以下脚本，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": {
"port": "8080"
}
}配置你的脚本的选项或参数。
你的包很可能依赖其他包。你可以在你的 package.json 文件里指定那些依赖。
这些是你的包的开发版和发布版都需要的依赖。
{
"dependencies": {
"package-1": "^3.1.4",
"package-2": "file:./path/to/dir",
"express": "expressjs/express",
"mocha": "mochajs/mocha#4727d357ea",
"module": "user/repo#feature/branch",
"cliz": "git+ssh://[email protected]:npm/cli.git#v1.0.27",
"clis": "git+ssh://[email protected]:npm/cli#semver:^5.0",
"clin": "git+https://[email protected]/npm/cli.git",
"clig": "git://github.com/npm/cli.git#v1.0.27",
"foo": "1.0.0 - 2.9999.9999",
"bar": ">=1.0.2 <2.1.2",
"baz": ">1.0.2 <=2.3.4",
"boo": "2.0.1",
"qux": "<1.0.0 || >=2.3.1 <2.4.5 || >=2.5.2 <3.0.0",
"asd": "http://asdf.com/asdf.tar.gz",
"til": "~1.2",
"elf": "~1.2.3",
"two": "2.x",
"thr": "3.3.x",
"lat": "latest",
"dyl": "file:../dyl"
}
}你可以指定一个确切的版本、一个最小的版本 (比如
>=) 或者一个版本范围 (比如>= ... <)。
包也可以指向本地的一个目录文件夹。
这些是只在你的包开发期间需要，但是生产环境不会被安装的包。
{
"devDependencies": {
"package-2": "^0.4.2"
}
}平行依赖允许你说明你的包和其他包版本的兼容性。
{
"peerDependencies": {
"package-3": "^2.7.18"
}
}添加可选设置以消除丢失的对等依赖性警告，#6671 。
{
"peerDependenciesMeta": {
"node-sass": {
"optional": true
},
"sass": {
"optional": true
},
"fibers": {
"optional": true
}
}
}可选依赖可以用于你的包，但不是必需的。如果可选包没有找到，安装还可以继续。
{
"optionalDependencies": {
"package-5": "^1.6.1"
}
}打包依赖是发布你的包时将会一起打包的一个包名数组。
{
"bundledDependencies": [
"package-4"
]
}如果您需要对依赖项的依赖项进行特定更改，例如用已知的安全问题替换依赖项的版本，用 fork 替换现有的依赖项，或者确保在所有地方都使用相同版本的包，那么 您可以添加 override。
为了确保包 foo 始终安装为 1.0.0 版本，无论您的依赖项依赖于哪个版本：
{
"overrides": {
"foo": "1.0.0"
}
}以上是简写符号，完整的对象形式可用于允许覆盖包本身以及包的子项。 这将导致 foo 始终为 1.0.0，同时也使 bar 在超出 foo 的任何深度也为 1.0.0：
{
"overrides": {
"foo": {
".": "1.0.0",
"bar": "1.0.0"
}
}
}仅当 foo 是包 bar 的子项（或孙子、曾孙等）时才将 foo 覆盖为 1.0.0：
{
"overrides": {
"bar": {
"foo": "1.0.0"
}
}
}键可以嵌套到任意长度。 仅当 foo 是 bar 的子项且仅当 bar 是 baz 的子项时才覆盖 foo：
{
"overrides": {
"baz": {
"bar": {
"foo": "1.0.0"
}
}
}
}overrides 的键还可以包括版本或版本范围。 将 foo 覆盖为 1.0.0，但仅当它是 [email protected] 的子代时：
{
"overrides": {
"[email protected]": {
"foo": "1.0.0"
}
}
}{
"dependencies": {
"foo": "^1.0.0"
},
"overrides": {
// 不好，会抛出 EOVERRIDE 错误
// "foo": "^2.0.0"
// 很好，规格匹配，因此允许覆盖
// "foo": "^1.0.0"
// 最好，覆盖被定义为对依赖项的引用
"foo": "$foo",
// 引用的包不需要匹配覆盖的包
"bar": "$foo"
}
}你可以提供和你的包关联的系统级的信息，比如操作系统兼容性之类。
指定使用你的包客户必须使用的版本，这将检查 process.versions 以及当前 yarn 版本。
{
"engines": {
"node": "^10.13.0 || ^12.13.0 || ^14.15.0 || >=15.0.0",
"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 检查不匹配。
此选项指定你的包的操作系统兼容性，它会检查 process.platform。
{
"os": ["darwin", "linux"],
"os": ["!win32"]
}使用这个选项指定你的包将只能在某些 CPU 体系架构上运行，这会检查 process.arch。
{
"cpu": ["x64", "ia32"],
"cpu": ["!arm", "!mips"]
}{
"private": true
}如果你不想你的包发布到包管理器(npm 或者 私有包管理)，设置为 true。
这些配置值将在你的包发布时使用。比如，你可以给包打标签。
{
"publishConfig": {
"registry": "https://registry.npm.taobao.org"
}
}这是一组将在发布时使用的配置值。 如果要设置标记，注册表或访问权限，则特别方便，以便确保给定的包未标记为 latest，发布到全局公共 registry 或默认情况下，作用域模块(@scoped)是私有的。
可以覆盖任何配置值，但只有 tag，registry 和 access 可能对于发布而言很重要，npm-config。
如果你的包只允许给定依赖的一个版本，你想强制和命令行上 yarn install --flat 相同的行为，把这个值设为 true。
{
"flat": true
}请注意，如果你的 package.json 包含 "flat": true 并且其它包依赖你的包 (比如你在构建一个库，而不是应用)， 其它那些包也需要在它们的 package.json 加上 "flat": true，或者在命令行上用 yarn install --flat 安装。
{
"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 字段。
As always, thanks to our amazing contributors!
Made with action-contributors.
Licensed under the MIT License.
![@github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=64&v=4){kind=small}