package.json

要点

你的 package.json 里两个最重要的字段是 name 和 version，没有它们你的包无法安装。 name 和 version 字段一起用来创建一个唯一 id。

`name`

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

这是你的包的名字。它在 URL 中、作为命令行参数、作为 node_modules 里的目录名使用。

yarn add [name]

node_modules/[name]


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

规则

必须少于或等于 214 个字符（对于限定域的包来说包括 @scope/）。
不能以句点 (.) 或者下划线 (_) 开头。
名字里不能有大写字母。
必须只使用 URL 安全的字符。

小建议

别用和 Node.js 核心模块相同的名字
比在名字里家 js 或者 node。
保持名字短小精悍。你想让人从名字上明白它是什么，它也会被用在 require() 调用里。
保证 registry 里没有什么是同名的。

`version`

{
  "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) 许可证，除非你有特别的原因不用它。如果你你构建的包是你工作的一部分，决定许可证前最好和公司一起检查一下。

必须是下面一种：

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

链接

各种链接指向文档、报告 issues 的地方和你的包代码托管在哪里。

`homepage`

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

homepage 是你的包的登陆页或文档的 URL。

`bugs`

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

你项目的问题跟踪系统的 URL。也可以是 email 地址或类似的东西。它为用户提供一个找到往哪里报告你的包的问题的途径。

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

repository 是你的包代码托管的地方。

维护者

你的项目的维护者。

`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": {
    "command-name": "bin/command-name.js",
    "other-command": "bin/other-command"
  }
}

将会和你项目一起被安装的可执行文件。

`man`

{
  "man": "./man/doc.1",
  "man": ["./man/doc.1", "./man/doc.2"]
}

如果你有 man pages 和你的项目关联，把它们加在这里。

`directories`

{
  "directories": {
    "lib": "path/to/lib/",
    "bin": "path/to/bin/",
    "man": "path/to/man/",
    "doc": "path/to/doc/",
    "example": "path/to/example/"
  }
}

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

任务

你的包可以包括可运行脚本或其它配置。

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

`config`

{
  "config": {
    "port": "8080"
  }
}

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

依赖

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

`dependencies`

{
  "dependencies": {
    "package-1": "^3.1.4"
  }
}

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

你可以指定一个确切的版本、一个最小的版本 (比如 >=) 或者一个版本范围 (比如 >= ... <)。

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

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

`flat`

{
  "flat": true
}

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

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

系统

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

`engines`

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

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

`os`

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

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

`cpu`

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

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

发布

`private`

{
  "private": true
}

如果你不想你的包发布到包管理器，设置为 true。

`publishConfig`

{
  "publishConfig": {
    ...
  }
}

这些配置值将在你的包发布时使用。比如，你可以给包打标签。

← 配置 envvars →