下面的内容基本都是从官方文档上整理过来的。介绍一些比较重要的字段,不太常见的就不写了。详细内容可以查看官方文档。
name 包名
如果你需要发布包,name
和 version
是必不可少的字段。如果不需要发布,那这两个是可选的。
name 的命名有一些规范:
- 长度 <= 214个字符,包含 scoped package 的 scope
- 如果是 scoped package, 名称可以以 . 和 _ 开头
- 不能包含大写字母
- 由于名称会作为 URL、命令行参数和文件夹名的一部分,所以不能包含不安全的 URL 字符
注意:
- 不要使用和核心 node 模块相同的名称
- 不要包含 "js" 或者 "node"
- 名称尽量精简、易于理解
- 命名前,检查一下 www.npmjs.com 是否有重复的 package
name 可以拥有前缀,e.g. @myorg/mypackage
。
version 版本号
需要符合 semver 的规范。e.g. 1.1.0
or 1.1.0-alpha.1
description 描述
package 的描述信息,是一个字符串。它可以被 npm search
查询到。 npm search sqlite
keywords 关键词
package 的关键词,是一个字符串数组。同样可以被 npm search
查询到。
homepage 首页
项目的首页
json
{
"homepage": "https://github.com/owner/project#readme"
}
bugs
issue tracker 的 url 或者 email 地址。可以直接提供一个对象或者 url 字符串
json
{
"bugs": {
"url" : "https://github.com/owner/project/issues",
"email" : "project@hostname.com"
}
}
json
{
"bugs": "https://github.com/owner/project/issues"
}
如果提供了 url,它可以被 npm bugs
命令使用,执行该命令会打开对应的网址。
license 许可证
参考 the full list of SPDX license IDs 选择合适的 identifier
json
{
"license": "BSD-3-Clause"
}
如果你不想授予其他人使用一个私有的或者未发布的 package,你可以这么写:
json
{
"license": "UNLICENSED"
}
并设置 "private": true
防止不小心发布 package。
author,contributors
author 包含 name
以及可选的 url
、email
。 例如
json
{
"name": "Barney Rubble",
"email": "b@rubble.com",
"url": "http://barnyrubble.tumblr.com/"
}
也可以直接一个字符串
json
{ "author": "Barney Rubble <b@rubble.com> (http://barnyrubble.tumblr.com/)" }
email 和 url 都是可选的。
files 文件
该字段是可选的,用于指定包发布时需要包含的文件或目录的字段。它的语法类似 .gitignore
,但是作用是相反的。
你也可以提供一个 .npmignore
文件,防止某些文件被上传。当 .gitignore
文件存在时,.npmignore
会被忽略。
某些文件总是会被上传,如:
package.json
README
LICENSE
/LICENCE
main
字段中指定的文件
README
和 LICENSE
可以使用任何大小写形式和文件扩展名
相应的,一些文件也总是会被忽略,如:
.git
CVS
.svn
.hg
.lock-wscript
.wafpickle-N
.*.swp
.DS_Store
._*
npm-debug.log
.npmrc
node_modules
config.gypi
*.orig
package-lock.json
main
main
字段用于指定一个模块 ID,表示包的主要入口点。当用户在程序中使用 require("your-package-name")
引入你的包时,main
字段所指定的模块将被返回。
通常情况下,main
字段的值是相对于包根目录的模块路径。例如,如果你的包名为 foo
,并且你的主模块位于 lib/index.js
,那么你可以在 package.json
文件中设置如下的 main
字段:
json
{
"name": "foo",
"version": "1.0.0",
"description": "My package",
"main": "lib/index.js"
}
这样,当用户在程序中使用 require("foo")
引入你的包时,lib/index.js
模块将被返回。
如果你的包只有一个主要的模块,那么通常情况下只需要设置 main
字段就可以了。如果你的包有多个模块,那么可以考虑使用 exports
字段来指定每个模块的入口点。
值得注意的是,如果你没有设置 main
字段,npm 会默认使用包根目录下的 index.js
作为主模块。因此,如果你的包的主模块就是 index.js
,那么可以省略 main
字段。
browser
如果你的模块是针对客户端浏览器使用的,那么应该使用 browser
字段来代替 main
字段。
使用 browser
字段的目的是为了解决在浏览器中使用 Node.js 模块的常见问题。在浏览器中,一些 Node.js 模块中常用的 API(例如 fs
、child_process
等)是不可用的,因此需要提供替代的实现或者使用其他的库来实现相同的功能。在这种情况下,使用 browser
字段可以指定一个浏览器端可用的模块路径或文件,这个路径或文件应该是相对于包根目录的。
例如,如果你的包有一个主模块 lib/main.js
,但是它依赖了 Node.js 模块 fs
,那么你可以在 package.json
文件中设置如下的 browser
字段:
json
{
"name": "my-package",
"version": "1.0.0",
"description": "My package",
"main": "lib/main.js",
"browser": "lib/main.browser.js"
}
在上面的示例中,我们指定了一个名为 lib/main.browser.js
的替代模块,用于在浏览器中使用。当用户在浏览器中使用你的包时,浏览器将加载 lib/main.browser.js
模块,而不是 lib/main.js
模块。
bin
bin
字段用于指定一个或多个可执行文件的名称和路径。当使用 npm install
命令安装该包时,这些可执行文件将会被安装到系统的 PATH
中,以便在命令行中直接运行。
具体来说,bin
字段是一个对象,其中的键表示可执行文件的名称,值表示可执行文件的路径。例如,假设你的包中有一个名为 my-script
的可执行文件,其路径为 ./bin/my-script.js
,那么你可以在 package.json
文件中添加以下内容:
json
{
"name": "my-package",
"version": "1.0.0",
"bin": {
"my-script": "./bin/my-script.js"
}
}
这告诉 npm
在安装时将 my-script
可执行文件添加到 PATH
中。这样,其他人在安装了你的包后就可以在命令行中直接运行 my-script
命令了。
如果你的包有多个可执行文件,可以在 bin
字段中添加多个键值对,每个键值对对应一个可执行文件。例如:
json
{
"name": "my-package",
"version": "1.0.0",
"bin": {
"my-script": "./bin/my-script.js",
"my-other-script": "./bin/my-other-script.js"
}
}
在这个例子中,my-package
包将会在安装时将两个可执行文件 my-script
和 my-other-script
添加到系统的 PATH
中。
另外,请确保你在 bin
中引用的文件,其内容是以 #!/usr/bin/env node
开头,不然无法执行。
repository
指定代码存放的位置。运行 npm docs
将打开对应的网址。
json
{
"repository": {
"type": "git",
"url": "https://github.com/npm/cli.git"
}
}
如果你的 package 是一个 monorepo
项目的一部分,你可以像这样指定目录:
json
{
"repository": {
"type": "git",
"url": "https://github.com/facebook/react.git"
"directory": "packages/react-dom"
}
}
config
config 可以给 scripts 提供配置,像这样:
json
{
"name": "test-npm-config",
"packageManager": "yarn@3.6.1",
"scripts": {
"start": "node index.js --port=$npm_package_config_port"
},
"config": {
"port": "8080"
}
}
只有通过 npm run start
才能访问到这个变量。如果要设置环境变量,更推荐使用 cross-env
scripts
scripts
属性支持一系列内置脚本和生命周期事件,以及自定义脚本。这些脚本可以通过运行 npm run-script <stage>
或 npm run <stage>
(简写)来执行。与之匹配的前置和后置命令也会被执行(例如 premyscript
、myscript
、postmyscript
)。还可以通过 npm explore <pkg> -- npm run <stage>
来运行依赖包中的脚本。
Life Cycle Scripts
有一些特别的生命周期脚本只会在某些情况下发生。
prepare
,prepublish
,prepublishOnly
,prepack
,postpack
,dependencies
prepare
这个适合执行编译构建之类的任务。
Environment
path
当执行 scripts
里的脚本时,./node_modules/.bin
等会被添加 PATH
中,所以你可以直接执行某些命令。
json
{
"scripts": {
"dev": "vite dev"
},
"devDependencies": {
"vite": "^4.4.7"
}
}
package.json vars
参考上面讲的 config
。 如果你的 package.json
文件中有 { "name": "foo", version: "1.2.5" }
, 那么在 scripts
中你就可以访问到 npm_package_name
和 npm_package_version
这两个环境变量。
dependencies
这个定义的是生产依赖,以下都是正确的写法。
json
{
"dependencies": {
"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"
}
}
Git URL
text
git+ssh://git@github.com:npm/cli.git#v1.0.27
git+ssh://git@github.com:npm/cli#semver:^5.0
git+https://isaacs@github.com/npm/cli.git
git://github.com/npm/cli.git#v1.0.27
Github URL
json
{
"name": "foo",
"version": "0.0.0",
"dependencies": {
"express": "expressjs/express",
"mocha": "mochajs/mocha#4727d357ea",
"module": "user/repo#feature\/branch"
}
}
Local Path
text
../foo/bar
~/foo/bar
./foo/bar
/foo/bar
json
{
"name": "baz",
"dependencies": {
"bar": "file:../foo/bar"
}
}
注意,当运行 npm install
时,通过本地路径链接的包将不会安装它们自己的依赖项。你必须在本地路径中运行 npm install
devDependenices
开发环境依赖。
overrides
overrides
用于覆盖 package.json
文件中的依赖项版本。
json
{
"name": "my-package",
"version": "1.0.0",
"dependencies": {
"react": "^16.0.0"
},
"devDependencies": {
"enzyme": "^3.0.0"
},
"overrides": {
"react": "^15.0.0",
"enzyme": "^2.0.0"
}Ï
}
上面 react
的版本被指定为 ^15.0.0
, enzyme
的版本被指定为 ^2.0.0
。这是比较常见的用法,还有其他的用法。比如依赖的子依赖版本也可以被修改。
json
{
"overrides": {
"foo": {
".": "1.0.0",
"bar": "1.0.0"
}
}
}
这里 foo
的版本指定为 1.0.0
, 它的依赖项 bar
被指定为 1.0.0
。官方文档
workspaces
这是 monorepo 项目会用到的字段,常见的配置如下。
json
{
"name": "workspace-example",
"workspaces": [
"./packages/*",
"./apps/*"
]
}
有关 workspaces
的详细内容,可以看官方文档