• 重要字段
    • name
    • version
  • 信息类字段
    • description
    • keywords
    • license
  • 链接类字段
    • homepage
    • bugs
    • repository
  • 项目维护类字段
    • author
    • contributors
  • 文件类信息
    • files
    • main
    • bin
    • man
    • directories
  • 任务类字段
    • scripts
    • config
  • 依赖描述类字段
    • dependencies
    • devDependencies
    • peerDependencies
    • optionalDependencies
    • bundledDependencies
    • flat
    • resolutions
  • 系统
    • engines
    • os
    • cpu
  • 发布
    • private
    • publishConfig

    重要字段

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

    name

    1. {
    2.   "name": "my-awesome-package"
    3. }

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

    1. yarn add [name]
    1. node_modules/[name]
    4. https://registry.npmjs.org/[name]/-/[name]-[version].tgz

    规则

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

    • 必须只使用 URL 安全的字符。
      Tips

    • 不要使用和 Node.js 核心模块相同的名字。

    • 不要在名字里包含 js 或者 node 单词。
    • 短小精悍，让人看到名字就大概了解包的功能，记住它也会被用在 require() 调用里。
    • 保证名字在 registry 里是唯一的。

    version

    1. {
    2.   "version": "1.0.0"
    3. }

    包的当前版本号。

    信息类字段

    description

    1. {
    2.   "description": "我的包的简短描述"
    3. }

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

    keywords

    1. {
    2.   "keywords": ["short", "relevant", "keywords", "for", "searching"]
    3. }

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

    license

    1. {
    2.   "license": "MIT",
    3.   "license": "(MIT or GPL-3.0)",
    4.   "license": "SEE LICENSE IN LICENSE_FILENAME.txt",
    5.   "license": "UNLICENSED"
    6. }

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

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

    license字段必须是以下之一：

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

    链接类字段

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

    homepage

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

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

    bugs

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

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

    repository

    1. {
    2.   "repository": { "type": "git", "url": "https://github.com/user/repo.git" },
    3.   "repository": "github:user/repo",
    4.   "repository": "gitlab:user/repo",
    5.   "repository": "bitbucket:user/repo",
    6.   "repository": "gist:a1b2c3d4e5f"
    7. }

    repository 是代码托管的位置。

    项目维护类字段

    项目的维护者。

    author

    1. {
    2.   "author": {
    3.     "name": "Your Name",
    4.     "email": "you@example.com",
    5.     "url": "http://your-website.com"
    6.   },
    7.   "author": "Your Name <you@example.com> (http://your-website.com)"
    8. }

    作者信息，一个人。

    contributors

    1. {
    2.   "contributors": [
    3.     { "name": "Your Friend", "email": "friend@example.com", "url": "http://friends-website.com" }
    4.     { "name": "Other Friend", "email": "other@example.com", "url": "http://other-website.com" }
    5.   ],
    6.   "contributors": [
    7.     "Your Friend <friend@example.com> (http://friends-website.com)",
    8.     "Other Friend <other@example.com> (http://other-website.com)"
    9.   ]
    10. }

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

    文件类信息

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

    files

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

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

    main

    1. {
    2.   "main": "filename.js"
    3. }

    项目的入口文件。

    bin

    1. {
    2.   "bin": "bin.js",
    3.   "bin": {
    4.     "command-name": "bin/command-name.js",
    5.     "other-command": "bin/other-command"
    6.   }
    7. }

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

    man

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

    和项目相关的文档页面（man page）。

    directories

    1. {
    2.   "directories": {
    3.     "lib": "path/to/lib/",
    4.     "bin": "path/to/bin/",
    5.     "man": "path/to/man/",
    6.     "doc": "path/to/doc/",
    7.     "example": "path/to/example/"
    8.   }
    9. }

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

    任务类字段

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

    scripts

    1. {
    2.   "scripts": {
    3.     "build-project": "node build-project.js"
    4.   }
    5. }

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

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

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

    config

    1. {
    2.   "config": {
    3.     "port": "8080"
    4.   }
    5. }

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

    依赖描述类字段

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

    dependencies

    1. {
    2.   "dependencies": {
    3.     "package-1": "^3.1.4"
    4.   }
    5. }

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

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

    devDependencies

    1. {
    2.   "devDependencies": {
    3.     "package-2": "^0.4.2"
    4.   }
    5. }

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

    peerDependencies

    1. {
    2.   "peerDependencies": {
    3.     "package-3": "^2.7.18"
    4.   }
    5. }

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

    optionalDependencies

    1. {
    2.   "optionalDependencies": {
    3.     "package-5": "^1.6.1"
    4.   }
    5. }

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

    bundledDependencies

    1. {
    2.   "bundledDependencies": ["package-4"]
    3. }

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

    flat

    1. {
    2.   "flat": true
    3. }

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

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

    resolutions

    1. {
    2.   "resolutions": {
    3.     "transitive-package-1": "0.0.29",
    4.     "transitive-package-2": "file:./local-forks/transitive-package-2",
    5.     "dependencies-package-1/transitive-package-3": "^2.1.1"
    6.   }
    7. }

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

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

    系统

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

    engines

    1. {
    2.   "engines": {
    3.     "node": ">=4.4.7 <7.0.0",
    4.     "zlib": "^1.2.8",
    5.     "yarn": "^0.14.0"
    6.   }
    7. }

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

    This check follows normal semver rules with one exception. It allows prerelease versions to match semvers that do not explicitly specify a prerelease. For example, 1.4.0-rc.0 matches >=1.3.0, while it would not match a typical semver check.

    os

    1. {
    2.   "os": ["darwin", "linux"],
    3.   "os": ["!win32"]
    4. }

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

    cpu

    1. {
    2.   "cpu": ["x64", "ia32"],
    3.   "cpu": ["!arm", "!mips"]
    4. }

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

    发布

    private

    1. {
    2.   "private": true
    3. }

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

    publishConfig

    1. {
    2.   "publishConfig": {
    3.     ...
    4.   }
    5. }

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

    原文: https://yarnpkg.com/zh-Hans/docs/package-json