package.json 备忘清单

package.json 备忘清单

这个快速参考备忘清单，显示了关于 package.json 文件中所需内容的全部内容。

重要字段

介绍

本快速参考备忘清单是您需要了解的关于 package.json 文件中所需内容的全部内容。它必须是实际的 JSON，而不仅仅是 JavaScript 对象字面量。

npm 文档 (npmjs.com)
yarnpkg 文档 (yarnpkg.com)

`name`

{
  "name": "my-awesome-package"
}

规则

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

`version`

{
  "version": "1.0.0"
}

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

Tips

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

如果没有 name 和version 字段，您的包将无法安装

安装 `name` 包

yarn add [包名]
# or
npm install [包名]

安装后存放位置

node_modules/[包名]

npmjs 下载地址

https://registry.npmjs.org/[包名]/-/[包名]-[version].tgz

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

信息类字段

`description`

{
  "description": "我的包的概要简短描述"
}

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

`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 字符串。

`keywords`

{
  "keywords": [
    "short", "relevant", "keywords"
  ]
}

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

链接类字段

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

`homepage`

{
  "homepage": "https://your-package.org"
}

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

`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"
}

包的实际代码所在的位置。

`bugs`

{
  "bugs": "https://github.com/user/repo/issues"
}

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

项目维护类字段

`author`

项目的维护者。

{
  "author": {
    "name": "Your Name",
    "email": "you@xxx.com",
    "url": "http://your-x.com"
  },
  "author": "Your Name <you@xxx.com> (http://your-x.com)"
}

作者信息，一个人。

`contributors`

{
  "contributors": [
    { "name": "Your Friend", "email": "friend@xxx.com", "url": "http://friends-xx.com" }
    { "name": "Other Friend", "email": "other@xxx.com", "url": "http://other-xx.com" }
  ],
  "contributors": [
    "Your Friend <friend@xxx.com> (http://friends-xx.com)",
    "Other Friend <other@xxx.com> (http://other-xx.com)"
  ]
}

贡献者信息，可能很多人。

文件类信息

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

`files`

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

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

`main`

{
  "main": "filename.js"
}

项目的入口文件。

`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、文档、例子等。

`bin`

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

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

`types`

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

{
  "types": "./lib/main.d.ts",
}

如果您的主声明文件名为 index.d.ts 并且位于包的根目录（index.js旁边），则不需要标记 types 属性，建议这样做。

打包包字段

`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"
  }
}

另请参阅：通过 npm 交付未编译的源代码

`module`

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

{
  "module": "dist/my-package.esm.js"
}

支持：rollup, webpack

`browser`

"browser": {
    "module-a": "./shims/module-a.js",
    "./server/only.js": "./shims/client-only.js"
}

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

任务类字段

包里还可以包含一些可执行脚本或者其他配置信息。

`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"
  }
}

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

{
  "scripts": {
    "run": "echo $npm_package_config_port"
  }
}

配置中的键作为环境变量公开给脚本(scripts)。

依赖描述类字段

你的包很可能依赖其他包。你可以在你的 package.json 文件里指定那些依赖。

`dependencies`

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

{
  "dependencies": {
    "colors":   "*",
    "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:./path/to/dyl",
    "pla": "https://github.com/user/project/tarball/branch",
    "stu": "git://github.com/user/project.git#commit-ish"
  }
}

你可以指定一个确切的版本、一个最小的版本 (比如 >=) 或者一个版本范围 (比如 >= ... <)。包也可以指向本地的一个目录文件夹。参考文档：npm docs.

workspaces

{
  "name": "my-workspaces-powered-project",
  "workspaces": [
    "./pkg/*",
    "packages/a",
    "packages/b"
  ]
}

支持从单个顶级根包中管理本地文件系统中的多个包。

├┈┈ node_modules
┆  ├┈┈ a -> ../packages/a
┆  ╰┈┈ b -> ../packages/b
├┈┈ package-lock.json
├┈┈ package.json
╰┈┈ packages
   ├┈┈ a
   ┆   ╰┈┈ package.json
   ├┈┈ b
   ┆   ╰┈┈ package.json

参考文档：workspaces

`devDependencies`

{
  "devDependencies": {
    "package-2": "^0.4.2"
  }
}

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

`overrides`

{
  "overrides": {
    "foo": "1.0.0"
  }
}

对依赖项的依赖项进行特定更改，例如用已知的安全问题替换依赖项的版本

`peerDependencies`

{
  "peerDependencies": {
    "package-3": "^2.7.18"
  }
}

平行依赖允许你说明你的包和其他包版本的兼容性。添加可选设置以消除丢失的对等依赖性警告，#6671 。

`optionalDependencies`

{
  "optionalDependencies": {
    "package-5": "^1.6.1"
  }
}

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

`bundledDependencies`

{
  "bundledDependencies": [
    "package-4"
  ]
}

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

`peerDependenciesMeta`

{
  "peerDependenciesMeta": {
    "node-sass": {
      "optional": true
    },
    "sass": {
      "optional": true
    },
    "fibers": {
      "optional": true
    }
  }
}

它允许对等依赖项标记为可选

系统

你可以提供和你的包关联的系统级的信息，比如操作系统兼容性之类。

`engines`

指定使用你的包客户必须使用的版本，这将检查 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 检查不匹配。

`os`

{
  "os": ["darwin", "linux"],
  "os": ["!win32"]
}

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

`cpu`

{
  "cpu": ["x64", "ia32"],
  "cpu": ["!arm", "!mips"]
}

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

发布

`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 字段。

另见

PACKAGE.JSON 中文说明 (github.io)

package.json 备忘清单

package.json 备忘清单

重要字段

介绍

name

version

Tips

安装 name 包

信息类字段

description

license

license字段必须是以下之一

keywords

链接类字段

homepage

repository

bugs

项目维护类字段

author

contributors

文件类信息

files

main

man

directories

bin

types

打包包字段

esnext

module

browser

任务类字段

scripts

特定的 scripts

config

依赖描述类字段

dependencies

workspaces

devDependencies

overrides

peerDependencies

optionalDependencies

bundledDependencies

peerDependenciesMeta

系统

engines

os

cpu

发布

private

publishConfig

Yarn

flat

resolutions

另见

`name`

`version`

安装 `name` 包

`description`

`license`

`keywords`

`homepage`

`repository`

`bugs`

`author`

`contributors`

`files`

`main`

`man`

`directories`

`bin`

`types`

`esnext`

`module`

`browser`

`scripts`

特定的 `scripts`

`config`

`dependencies`

`devDependencies`

`overrides`

`peerDependencies`

`optionalDependencies`

`bundledDependencies`

`peerDependenciesMeta`

`engines`

`os`

`cpu`

`private`

`publishConfig`

`flat`

`resolutions`