这个快速参考备忘清单,显示了关于 package.json 文件中所需内容的全部内容。
本快速参考备忘清单是您需要了解的关于 package.json 文件中所需内容的全部内容。 它必须是实际的 JSON,而不仅仅是 JavaScript 对象字面量。
name
{
"name": "my-awesome-package"
}
@scope/
范围包).
)或下划线(_
)开头version
{
"version": "1.0.0"
}
包的当前版本,严格遵循 Semantic Versioning 2.0.0 语义化版本规范。
Node.js
核心模块相同的名字。js
或者 node
单词。require()
调用里。如果没有 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) 许可证,除非你有特别的原因不用它。 如果你开发的包是你工作的一部分,最好和公司讨论后再做决定。
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 交付未编译的源代码
browser
"browser": {
"module-a": "./shims/module-a.js",
"./server/only.js": "./shims/client-only.js"
}
字段由模块作者提供,作为 JavaScript
包或组件工具的提示,用于打包模块以供客户端使用。 提案就在这里。
exports
{
"name": "mod",
"exports":{
".": "./lib/index.js",
"./lib/*": "./lib/*.js"
}
}
使用最新的 exports
字段导出,可规避 main
字段局限性 具体参考
{
"name": "mod",
"exports": {
".": "./index.js",
"./sub": "./src/sub.js"
}
}
导入
import sub from "mod/sub"
.
唯一的导出){
"exports": {
".": "./dist/index.js"
}
}
简写
{
"exports": "./dist/index.js"
}
:- | - |
---|---|
export | 通过 import 或 import() 或 es 模块加载的任何顶层导入或解析操作加载时,匹配。 |
require | 当包通过 require() 加载时匹配。预期的格式包括 CommonJS、JSON 和本地插件。 |
node | 匹配任何 Node.js 环境。可以是 cjs 或 es 模块文件。必须在 import 或 require 之后。 |
default | 默认的降级条件。可以是一个 cjs 或 es 模块文件。这个条件应该总是排在最后。 |
{
"exports": {
".": {
"import":"./dist/index.mjs",
"require":"./dist/index.cjs", // 当包通过 `require()` 加载时匹配
"node": "./dist/ployfill.js", // 匹配任何 `Node.js` 环境
"default": "./dist/default.js" // 默认的降级条件
}
}
}
require
和 import
互斥,所以 require
不能加载 es
的模块,export
不能加载 cjs
模块
main
Vs exports
{
"main": "./index.js",
"exports": "./index.js"
}
如果同时出现 main
exports
字段,只会读取 exports
字段
包里还可以包含一些可执行脚本或者其他配置信息。
scripts
脚本是定义自动化开发相关任务的好方法,比如使用一些简单的构建过程或开发工具。 在 scripts
字段里定义的脚本,可以通过 yarn run <script>
命令来执行。 例如,下面 build-project
脚本可以通过 yarn run build-project
调用,并执行 node build-project.js
。
{
"scripts": {
"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.
{
"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
}
}
}
它允许对等依赖项标记为可选
你可以提供和你的包关联的系统级的信息,比如操作系统兼容性之类。
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。
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
字段。