top

Buy me a coffee

文档主要来源于 yarnpkgnpm 官方文档,并不是完全复制,增加了一些内容和一些描述,作为笔记存储。你也可以参考 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 中最重要的两个字段是 nameversion,如果没有它们,您的包将无法安装。 nameversion 字段一起用于创建唯一ID。

name

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

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

yarn add [包名]
# or
npm install [包名]
node_modules/[包名]
https://registry.npmjs.org/[包名]/-/[包名]-[version].tgz

规则

Tips

version

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

{
  "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) 许可证,除非你有特别的原因不用它。 如果你开发的包是你工作的一部分,最好和公司讨论后再做决定。

license字段必须是以下之一:

链接类字段

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

homepage

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

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

bugs

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

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

repository

是代码托管的位置,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

作者信息,一个人。

{
  "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": {
    "命令名称": "bin/命令路径/命令名称.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/"
  }
}

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

types

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

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

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

打包包字段

module

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

支持:rollup, webpack

browser

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

esnext

完整的提案在这里。 简短说明:

{
  "main": "main.js",
  "esnext": {
    "main": "main-esnext.js",
    "browser": "browser-specific-main-esnext.js"
  }
}

另请参阅:Delivering untranspiled source code via npm

任务类字段

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

scripts

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

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

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

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

参考文档:npm docs

特定的 scripts

对于以下脚本,npm 支持 package.json 文件的 scripts 默认命令字段:

参考文档:npm docs.

config

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

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

依赖描述类字段

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

dependencies

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

{
  "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://git@github.com:npm/cli.git#v1.0.27",
    "clis": "git+ssh://git@github.com:npm/cli#semver:^5.0",
    "clin": "git+https://isaacs@github.com/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

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

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

peerDependencies

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

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

peerDependenciesMeta

添加可选设置以消除丢失的对等依赖性警告,#6671

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

optionalDependencies

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

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

bundledDependencies

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

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

overrides

如果您需要对依赖项的依赖项进行特定更改,例如用已知的安全问题替换依赖项的版本,用 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,但仅当它是 bar@2.0.0 的子代时:

{
  "overrides": {
    "bar@2.0.0": {
      "foo": "1.0.0"
    }
  }
}
{
  "dependencies": {
    "foo": "^1.0.0"
  },
  "overrides": {
    // 不好,会抛出 EOVERRIDE 错误
    // "foo": "^2.0.0"
    // 很好,规格匹配,因此允许覆盖
    // "foo": "^1.0.0"
    // 最好,覆盖被定义为对依赖项的引用
    "foo": "$foo",
    // 引用的包不需要匹配覆盖的包
    "bar": "$foo"
  }
}

系统

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

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

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

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

cpu

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

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

发布

private

{
  "private": true
}

如果你不想你的包发布到包管理器(npm 或者 私有包管理),设置为 true

publishConfig

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

{
  "publishConfig": {
    "registry": "https://registry.npm.taobao.org"
  }
}

这是一组将在发布时使用的配置值。 如果要设置标记,注册表或访问权限,则特别方便,以便确保给定的包未标记为 latest,发布到全局公共 registry 或默认情况下,作用域模块(@scoped)是私有的。

可以覆盖任何配置值,但只有 tagregistryaccess 可能对于发布而言很重要,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 字段。

Contributors

As always, thanks to our amazing contributors!

Made with action-contributors.

License

Licensed under the MIT License.