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() 调用中使用。
确保注册表中没有名称相同的条目。

`version`

{
  "version": "1.0.0"
}

你的软件包的当前版本。

信息

`description`

{
  "description": "My short description of my awesome package"
}

描述只是一个字符串，用于帮助人们理解软件包的目的。它还可以在软件包管理器中搜索软件包时使用。

`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 批准的) 许可证。如果你在工作中构建软件包，最好在决定使用哪种许可证之前咨询你的公司。

以下为可选许可证：

如果你使用的是标准许可证，则是一个有效的 SPDX 许可证标识符。
如果你使用的是多个标准许可证，则是一个有效的 SPDX 许可证表达式语法 2.0 表达式。
如果使用的是非标准许可证，SEE LICENSE IN <文件名> 字符串将指向您的包顶层中的 <文件名>。
如果您不想赋予他人使用任何条款下的私有或未发布包的权利，则使用 UNLICENSED 字符串。

链接

到文档、提交问题的位置以及包代码实际存在位置的各种链接。

`homepage`

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

主页是您包的登录页面或文档的 URL。

`bugs`

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

到项目问题追踪器的 URL。它还可以是电子邮件地址等内容。向用户提供获取有关向您的包提交问题的具体位置的方法。

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

仓库是包的实际代码所在的位置。

维护者

您项目的维护者。

`author`

{
  "author": {
    "name": "Your Name",
    "email": "[email protected]",
    "url": "http://your-website.com"
  },
  "author": "Your Name <[email protected]> (http://your-website.com)"
}

包作者信息。作者是一个人。

`contributors`

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

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

如果您有与项目关联的手册页，请将其添加到此处。

`directories`

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

在安装包时，您可以指定放置二进制文件、手册页、文档、示例等的位置。

任务

您的包可以包含可运行脚本或其他配置。

`scripts`

{
  "scripts": {
    "build-project": "node build-project.js"
  }
}

脚本非常适合自动执行与包相关的任务，例如简单的构建过程或开发工具。使用 "scripts" 字段，您可以定义各种脚本作为 yarn run <script> 运行。例如，上述 build-project 脚本可以用 yarn run build-project 调用，并将运行 node build-project.js。

某些脚本名称为特殊名称。如果已定义，yarn 在安装包之前会调用 preinstall 脚本。考虑到兼容性，在包安装完成后，名为 install、postinstall、prepublish 和 prepare 的脚本都会被调用。

默认情况下，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"
  }
}

对等依赖项允许你声明你的程序包与其他程序包版本之间的兼容性。

`peerDependenciesMeta`

{
  "peerDependenciesMeta": {
    "package-3": {
      "optional": true
    }
  }
}

允许你向对等依赖项中添加元数据。

目前，仅 optional 标签可用。将其设置为 true，将取消对缺少对等依赖项的警告。

`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 进行安装。

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

系统

您可以提供与您的包关联的系统级信息，例如操作系统兼容性等。

`engines`

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

引擎指定必须与你的程序包一起使用的客户端版本。此操作将根据 process.versions 以及 Yarn 的当前版本进行检查。

此检查遵循常规语义版本控制规则，但有一个例外。它允许预发布版本与未明确指定预发布版本的语义版本控制相匹配。例如，1.4.0-rc.0 匹配 >=1.3.0，但它不匹配典型的语义版本控制检查。

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