该节部分内容翻译自下述网站，作个人笔记之用。

• npmjs.com
• docs.npmjs.com

1.NPM CLI

本节总结了 npm 命令行工具的使用方法。

该节 Commands 是基于[email protected]。

npm access

Set access level on published packages.

Usage:

1. npm access public [<package>]
2. npm access restricted [<package>]
3. npm access grant <read-only|read-write> <scope:team> [<package>]
4. npm access revoke <scope:team> [<package>]
5. npm access 2fa-required [<package>]
6. npm access 2fa-not-required [<package>]
7. npm access ls-packages [<user>|<scope>|<scope:team>]
8. npm access ls-collaborators [<package> [<user>]]
9. npm access edit [<package>]

Options:

• [--registry <registry>]
• [--otp <otp>]

npm adduser

Add a registry user account.

Usage:

1. npm adduser

Options:

1. [--registry <registry>]
2. [--scope <@scope>]

npm audit

Run a security audit.

Usage:

1. npm audit 进行安全漏洞检测
2. npm audit fix 进行安全漏洞检测，并进行修复

Options:

• [--audit-level <info|low|moderate|high|critical|none>]
• [--dry-run]
• [-f|--force]
• [--json]
• [--package-lock-only]
• [--omit <dev|optional|peer> [--omit <dev|optional|peer> ...]]
• [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
• [-ws|--workspaces]
• [--include-workspace-root]

npm bugs

Report bugs for a package in a web browser.

Usage:

1. npm bugs [<pkgname>]

Options:

• [--no-browser|--browser <browser>]
• [--registry <registry>]

npm cache

Manipulates packages cache.

Usage:

1. npm cache add <tarball file>
2. npm cache add <folder>
3. npm cache add <tarball url>
4. npm cache add <git url>
5. npm cache add <name>@<version>
6. npm cache clean [<key>]
7. npm cache ls [<name>@<version>]
8. npm cache verify

Options:

• [--cache <cache>]

npm ci

Install a project with a clean slate.

Usage:

1. npm ci

Options:

• [--no-audit]
• [--ignore-scripts]
• [--script-shell <script-shell>]

npm completion

Tab Completion for npm.

Usage:

1. npm completion

npm config

Manage the npm configuration files.

Usage:

1. npm config set <key>=<value> [<key>=<value> ...]
2. npm config get [<key> [<key> ...]]
3. npm config delete <key> [<key> ...]
4. npm config list [--json]
5. npm config edit

Options:

• [--json]
• [-g|--global]
• [--editor <editor>]
• [-L|--location <global|user|project>]
• [-l|--long]

npm dedupe

Reduce duplication in the package tree.

Usage:

1. npm dedupe

Options:

• [--global-style]
• [--legacy-bundling]
• [--strict-peer-deps]
• [--no-package-lock]
• [--omit <dev|optional|peer> [--omit <dev|optional|peer> ...]]
• [--ignore-scripts]
• [--no-audit]
• [--no-bin-links]
• [--no-fund]
• [--dry-run]
• [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
• [-ws|--workspaces]
• [--include-workspace-root]

npm deprecate

Deprecate a version of a package.

Usage:

1. npm deprecate <pkg>[@<version>] <message>

Options:

• [--registry <registry>]
• [--otp <otp>]

npm diff

The registry diff command.

Usage:

1. npm diff [...<paths>]

Options:

• [--diff <pkg-name|spec|version> [--diff <pkg-name|spec|version> ...]]
• [--diff-name-only]
• [--diff-unified <number>]
• [--diff-ignore-all-space]
• [--diff-no-prefix]
• [--diff-src-prefix <path>]
• [--diff-dst-prefix <path>]
• [--diff-text]
• [-g|--global]
• [--tag <tag>]
• [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
• [-ws|--workspaces]
• [--include-workspace-root]

npm dist-tag

Modify package distribution tags.

Usage:

1. npm dist-tag add <pkg>@<version> [<tag>]
2. npm dist-tag rm <pkg> <tag>
3. npm dist-tag ls [<pkg>]

Options:

• [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
• [-ws|--workspaces]
• [--include-workspace-root]

npm docs

Open documentation for a package in a web browser.

Usage:

1. npm docs [<pkgname> [<pkgname> ...]]

Options:

• [--no-browser|--browser <browser>]
• [--registry <registry>]
• [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
• [-ws|--workspaces]
• [--include-workspace-root]

npm doctor

Check your npm environment.

Usage:

1. npm doctor

Options:

• [--registry <registry>]

npm edit

Edit an installed package.

Usage:

1. npm edit <pkg>[/<subpkg>...]

Options:

• [--editor <editor>]

npm exec

Run a command from a local or remote npm package.

Usage:

1. npm exec -- <pkg>[@<version>] [args...]
2. npm exec --package=<pkg>[@<version>] -- <cmd> [args...]
3. npm exec -c '<cmd> [args...]'
4. npm exec --package=foo -c '<cmd> [args...]'

Options:

• [--package <pkg>[@<version>]
• [--package <pkg>[@<version>] ...]]
• [-c|--call <call>]
• [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
• [-ws|--workspaces]
• [--include-workspace-root]

npm explain

Explain installed packages.

Usage:

1. npm explain <folder | specifier>

Options:

• [--json]
• [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]

npm explore

Browse an installed package.

Usage:

1. npm explore <pkg> [ -- <command>]

Options:

• [--shell <shell>]

npm find-dupes

Find duplication in the package tree.

Usage:

1. npm find-dupes

Options:

• [--global-style]
• [--legacy-bundling]
• [--strict-peer-deps]
• [--no-package-lock]
• [--omit <dev|optional|peer> [--omit <dev|optional|peer> ...]]
• [--ignore-scripts]
• [--no-audit]
• [--no-bin-links]
• [--no-fund]
• [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
• [-ws|--workspaces]
• [--include-workspace-root]

npm fund

Retrieve funding information.

Usage:

1. npm fund [[<@scope>/]<pkg>]

Options:

• [--json]
• [--no-browser|--browser <browser>]
• [--no-unicode]
• [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
• [--which <fundingSourceNumber>]

npm help

Get help on npm.

Usage:

1. npm help <term> [<terms..>]

Options:

• [--viewer <viewer>]

npm help-search

Search npm help documentation.

Usage:

1. npm help-search <text>

Options:

• [-l|--long]

npm hook

Manage registry hooks.

Usage:

1. npm hook add <pkg> <url> <secret> [--type=<type>]
2. npm hook ls [pkg]
3. npm hook rm <id>
4. npm hook update <id> <url> <secret>

Options:

• [--registry <registry>] [--otp <otp>]

npm init

Create a package.json file.

Usage:

1. npm init [--force|-f|--yes|-y|--scope]
2. npm init <@scope> (same as npx <@scope>/create)
3. npm init [<@scope>/]<name> (same as npx [<@scope>/]create-<name>)

Options:

• [-y|--yes]
• [-f|--force]
• [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
• [-ws|--workspaces]
• [--include-workspace-root]

npm install

Install a package.

Usage:

1. npm install [<@scope>/]<pkg>
2. npm install [<@scope>/]<pkg>@<tag>
3. npm install [<@scope>/]<pkg>@<version>
4. npm install [<@scope>/]<pkg>@<version range>
5. npm install <alias>@npm:<name>
6. npm install <folder>
7. npm install <tarball file>
8. npm install <tarball url>
9. npm install <git:// url>
10. npm install <github username>/<github project>

Options:

• [-S|--save|--no-save|--save-prod|--save-dev|--save-optional|--save-peer]
• [-E|--save-exact]
• [-g|--global]
• [--global-style]
• [--legacy-bundling]
• [--strict-peer-deps]
• [--no-package-lock]
• [--omit <dev|optional|peer> [--omit <dev|optional|peer> ...]]
• [--ignore-scripts]
• [--no-audit]
• [--no-bin-links]
• [--no-fund]
• [--dry-run]
• [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
• [-ws|--workspaces]
• [--include-workspace-root]

npm install-ci-test

Install a project with a clean slate and run tests.

Usage:

1. npm install-ci-test

Options:

• [--no-audit]
• [--ignore-scripts]
• [--script-shell <script-shell>]

npm install-test

Install package(s) and run tests.

Usage:

1. npm install-test [<@scope>/]<pkg>
2. npm install-test [<@scope>/]<pkg>@<tag>
3. npm install-test [<@scope>/]<pkg>@<version>
4. npm install-test [<@scope>/]<pkg>@<version range>
5. npm install-test <alias>@npm:<name>
6. npm install-test <folder>
7. npm install-test <tarball file>
8. npm install-test <tarball url>
9. npm install-test <git:// url>
10. npm install-test <github username>/<github project>

Options:

• [-S|--save|--no-save|--save-prod|--save-dev|--save-optional|--save-peer]
• [-E|--save-exact]
• [-g|--global]
• [--global-style]
• [--legacy-bundling]
• [--strict-peer-deps]
• [--no-package-lock]
• [--omit <dev|optional|peer> [--omit <dev|optional|peer> ...]]
• [--ignore-scripts]
• [--no-audit]
• [--no-bin-links]
• [--no-fund]
• [--dry-run]
• [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
• [-ws|--workspaces]
• [--include-workspace-root]

npm link

Symlink a package folder.

Usage:

1. npm link (in package dir)
2. npm link [<@scope>/]<pkg>[@<version>]

Options:

• [-S|--save|--no-save|--save-prod|--save-dev|--save-optional|--save-peer]
• [-E|--save-exact]
• [-g|--global]
• [--global-style]
• [--legacy-bundling]
• [--strict-peer-deps]
• [--no-package-lock]
• [--omit <dev|optional|peer> [--omit <dev|optional|peer> ...]]
• [--ignore-scripts]
• [--no-audit]
• [--no-bin-links]
• [--no-fund]
• [--dry-run]
• [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
• [-ws|--workspaces]
• [--include-workspace-root]

npm login

Add a registry user account.

Usage:

1. npm login

Options:

• [--registry <registry>]
• [--scope <@scope>]

aliases:

• adduser
• add-user

:::tip npm login 该命令与 npm adduser 执行一致。 :::

npm logout

Log out of the registry.

Usage:

1. npm logout

Options:

• [--registry <registry>]
• [--scope <@scope>]

npm ls

List installed packages.

Usage:

1. npm ls [[<@scope>/]<pkg> ...]

Options:

• [-a|--all]
• [--json]
• [-l|--long]
• [-p|--parseable]
• [-g|--global]
• [--depth <depth>]
• [--omit <dev|optional|peer> [--omit <dev|optional|peer> ...]]
• [--link]
• [--package-lock-only]
• [--no-unicode]
• [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
• [-ws|--workspaces]
• [--include-workspace-root]

npm org

Manage orgs.

Usage:

1. npm org set orgname username [developer | admin | owner]
2. npm org rm orgname username
3. npm org ls orgname [<username>]

Options:

• [--registry <registry>]
• [--otp <otp>]
• [--json]
• [-p|--parseable]

npm outdated

Check for outdated packages.

Usage:

1. npm outdated [[<@scope>/]<pkg> ...]

Options:

• [-a|--all]
• [--json]
• [-l|--long]
• [-p|--parseable]
• [-g|--global]
• [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]

npm owner

Manage package owners.

Usage:

1. npm owner add <user> [<@scope>/]<pkg>
2. npm owner rm <user> [<@scope>/]<pkg>
3. npm owner ls [<@scope>/]<pkg>

Options:

• [--registry <registry>]
• [--otp <otp>]

npm pack

Create a tarball from a package.

Usage:

1. npm pack [[<@scope>/]<pkg>...]

Options:

• [--dry-run]
• [--json]
• [--pack-destination <pack-destination>]
• [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
• [-ws|--workspaces]
• [--include-workspace-root]

npm ping

Ping npm registry.

Usage:

1. npm ping

Options:

• [--registry <registry>]

npm pkg

Manages your package.json.

Usage:

1. npm pkg set <key>=<value> [<key>=<value> ...]
2. npm pkg get [<key> [<key> ...]]
3. npm pkg delete <key> [<key> ...]

Options:

• [-f|--force]
• [--json]
• [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
• [-ws|--workspaces]

npm prefix

Display prefix.

Usage:

1. npm prefix [-g]

Options:

• [-g|--global]

npm profile

Change settings on your registry profile.

Usage:

1. npm profile enable-2fa [auth-only|auth-and-writes]
2. npm profile disable-2fa
3. npm profile get [<key>]
4. npm profile set <key> <value>

Options:

• [--registry <registry>]
• [--json]
• [-p|--parseable]
• [--otp <otp>]

npm prune

Remove extraneous packages.

Usage:

1. npm prune [[<@scope>/]<pkg>...]

Options:

• [--omit <dev|optional|peer> [--omit <dev|optional|peer> ...]]
• [--dry-run]
• [--json]
• [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
• [-ws|--workspaces]
• [--include-workspace-root]

npm publish

Publish a package.

Usage:

1. npm publish [<folder>]

Options:

• [--tag <tag>]
• [--access <restricted|public>]
• [--dry-run]
• [--otp <otp>]
• [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
• [-ws|--workspaces]
• [--include-workspace-root]

npm query

The npm query command allows for usage of css selectors in order to retrieve an array of dependency objects.

Usage:

1. npm query <selector>

npm rebuild

Rebuild a package.

Usage:

1. npm rebuild [[<@scope>/]<name>[@<version>] ...]

Options:

• [-g|--global]
• [--no-bin-links]
• [--ignore-scripts]
• [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
• [-ws|--workspaces]
• [--include-workspace-root]

npm repo

Open package repository page in the browser.

Usage:

1. npm repo [<pkgname> [<pkgname> ...]]

Options:

• [--no-browser|--browser <browser>]
• [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
• [-ws|--workspaces]
• [--include-workspace-root]

npm restart

Restart a package.

Usage:

1. npm restart [-- <args>]

Options:

• [--ignore-scripts]
• [--script-shell <script-shell>]

npm root

Display npm root

Usage:

1. npm root

Options:

• [-g|--global]

npm run-script

Run arbitrary package scripts.

Usage:

1. npm run-script <command> [-- <args>]

Options:

• [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
• [-ws|--workspaces]
• [--include-workspace-root]
• [--if-present]
• [--ignore-scripts]
• [--script-shell <script-shell>]

npm search

Search for packages.

Usage:

1. npm search [search terms ...]

Options:

• [-l|--long]
• [--json]
• [--color|--no-color|--color always]
• [-p|--parseable]
• [--no-description]
• [--searchopts <searchopts>]
• [--searchexclude <searchexclude>]
• [--registry <registry>]
• [--prefer-online]
• [--prefer-offline]
• [--offline]

npm shrinkwrap

Lock down dependency versions for publication.

Usage:

1. npm shrinkwrap

npm star

Mark your favorite packages.

Usage:

1. npm star [<pkg>...]

Options:

• [--registry <registry>]
• [--no-unicode]

npm stars

View packages marked as favorites.

Usage:

1. npm stars [<user>]

Options:

• [--registry <registry>]

npm start

Start a package.

Usage:

1. npm start [-- <args>]

Options:

• [--ignore-scripts]
• [--script-shell <script-shell>]

npm stop

Stop a package.

Usage:

1. npm stop [-- <args>]

Options:

• [--ignore-scripts]
• [--script-shell <script-shell>]

npm team

Manage organization teams and team memberships.

Usage:

1. npm team create <scope:team> [--otp <otpcode>]
2. npm team destroy <scope:team> [--otp <otpcode>]
3. npm team add <scope:team> <user> [--otp <otpcode>]
4. npm team rm <scope:team> <user> [--otp <otpcode>]
5. npm team ls <scope>|<scope:team>

Options:

• [--registry <registry>]
• [--otp <otp>]
• [-p|--parseable] [--json]

npm test

Test a package.

Usage:

1. npm test [-- <args>]

Options:

• [--ignore-scripts]
• [--script-shell <script-shell>]

npm token

Manage your authentication tokens.

Usage:

1. npm token list
2. npm token revoke <id|token>
3. npm token create [--read-only] [--cidr=list]

Options:

• [--read-only]
• [--cidr <cidr> [--cidr <cidr> ...]]
• [--registry <registry>]
• [--otp <otp>]

npm uninstall

Remove a package.

Usage:

1. npm uninstall [<@scope>/]<pkg>...

Options:

• [-S|--save|--no-save|--save-prod|--save-dev|--save-optional|--save-peer]
• [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
• [-ws|--workspaces]
• [--include-workspace-root]

npm unpublish

Remove a package from the registry.

Usage:

1. npm unpublish [<@scope>/]<pkg>[@<version>]

Options:

• [--dry-run]
• [-f|--force]
• [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
• [-ws|--workspaces]

npm update

Update packages.

Usage:

1. npm update [<pkg>...]

Options:

• [-g|--global]
• [--global-style]
• [--legacy-bundling]
• [--strict-peer-deps]
• [--no-package-lock]
• [--omit <dev|optional|peer> [--omit <dev|optional|peer> ...]]
• [--ignore-scripts]
• [--no-audit]
• [--no-bin-links]
• [--no-fund]
• [--dry-run]
• [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
• [-ws|--workspaces]
• [--include-workspace-root]

npm version

Bump a package version.

Usage:

1. npm version [<newversion> | major | minor | patch | premajor | preminor | prepatch | prerelease | from-git]

Options:

• [--allow-same-version]
• [--no-commit-hooks]
• [--no-git-tag-version]
• [--json]
• [--preid prerelease-id]
• [--sign-git-tag]
• [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
• [-ws|--workspaces]
• [--include-workspace-root]

npm view

View registry info.

Usage:

1. npm view [<@scope>/]<pkg>[@<version>] [<field>[.subfield]...]

Options:

• [--json]
• [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
• [-ws|--workspaces]
• [--include-workspace-root]

npm whoami

Display npm username.

Usage:

1. npm whoami

Options:

• [--registry <registry>]

npx

Run a command from a local or remote npm package.

Usage:

1. npm exec -- <pkg>[@<version>] [args...]
2. npm exec --package=<pkg>[@<version>] -- <cmd> [args...]
3. npm exec -c '<cmd> [args...]'
4. npm exec --package=foo -c '<cmd> [args...]'

Options:

• [--package <pkg>[@<version>]
• [--package <pkg>[@<version>] ...]]
• [-c|--call <call>]
• [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
• [-ws|--workspaces] [--include-workspace-root]

:::tip npx 命令与 npm exec 命令执行一致。

实际上，npx 是 npm exec 的别名。 :::

2.NPM Hooks

在 Node.js 开发中，npm 是一个包管理器，用于安装、更新和管理 JavaScript 模块。

npm 提供了一些钩子（hooks）机制，用于在特定的生命周期事件发生时执行自定义的操作。

npm 钩子（npm hooks）允许您在执行特定的npm命令时执行自定义的脚本或任务。

这些钩子可以用于在安装依赖、更新依赖、构建项目等过程中添加额外的自定义逻辑。

一些常见的 npm 钩子有：

1. preinstall：在执行 npm install 命令之前运行，可以用于在安装依赖之前进行一些预处理操作。
2. postinstall：在执行 npm install 命令之后运行，可以用于在安装依赖之后执行一些操作，如编译源代码、生成静态文件等。
3. prepublish：在执行 npm publish 命令之前运行，可以用于在发布模块之前执行一些操作，如打包、压缩等。
4. postpublish：在执行 npm publish 命令之后运行，可以用于在发布模块之后执行一些操作，如发送通知、更新文档等。
5. preversion：在执行 npm version 命令之前运行，可以用于在更新模块版本号之前执行一些操作。
6. postversion：在执行 npm version 命令之后运行，可以用于在更新模块版本号之后执行一些操作，如生成 changelog、提交代码等。

:::tip 除了上述 hooks，其他命令也有对应的钩子，pre 前缀表示前置钩子，post 前缀表示后置钩子。 :::

可以在项目的 package.json 文件中的 scripts 字段中定义这些钩子，并指定要运行的脚本命令。

当相关的 npm 命令被执行时，相应的钩子脚本将被调用。

譬如在 package.json 中添加：

{
  "scripts": {
    "preinstall": "echo \"preinstall script\""
  }
}

当执行 npm install 命令时，将会提前输出 preinstall script。

3.package.json

package.json

name

如果计划发布一个包，在 package.json 文件中，最重要的是 name 和 version 字段，因为它们是必需的。

name 和 version 组合起来形成一个被认为是完全唯一的标识符。

对包的更改应该伴随着版本的更改。如果你不计划发布你的包，name 和 version 字段是可选的。

name 是你的项目的名称。

一些规则：

1. 名称必须小于等于 214 个字符，包括作用域（对于作用域包）。
2. 带有作用域的包的名称可以以点（.）或下划线（_）开头，但是不能没有作用域。
3. 新的包名称不能包含大写字母。
4. 名称最终会成为 URL 的一部分、命令行的参数和文件夹名称。因此，名称不能包含任何非 URL 安全的字符。

一些建议：

1. 不要使用与核心 Node 模块相同的名称。
2. 不要在名称中包含 js 或 node。因为你编写的是 package.json 文件，所以可以假设是 JavaScript，而可以使用 engines 字段指定引擎。
3. 名称可能会作为参数传递给 require() 函数，所以它应该是一个简短但合理描述的名称。
4. 在你对名称过于依赖之前，可能需要检查 npm 注册表，看看是否已经有相同名称的包存在。npmjs.com
5. 名称可以选择性地添加作用域前缀，例如 @myorg/mypackage。

version

version 字段用于标识包的版本号，它应该遵循语义化版本控制规范，并且在发布新版本时进行适当的升级。

version 必须是可被 semver 解析的，semver 是作为 npm 的一个依赖项捆绑在一起的。（你可以使用 npm install semver 来自己使用它。）

npm 使用语义化版本控制（Semantic Versioning）规范来管理版本号。

语义化版本控制分为三个部分：主版本号、次版本号和补丁版本号。具体规则如下：

1. 主版本号（Major）：当你做了不兼容的 API 修改时，应该升级主版本号。
2. 次版本号（Minor）：当你添加了向后兼容的功能时，应该升级次版本号。
3. 补丁版本号（Patch）：当你进行向后兼容的 bug 修复时，应该升级补丁版本号。
4. 版本号可以包含预发布标识（如 beta、alpha）和构建标识（如 build-123）。

例如，一个有效的版本号可以是 1.0.0，2.3.1，1.2.0-beta.1 等。

当你发布新的版本时，你应该根据你的修改类型适当地升级主版本号、次版本号或补丁版本号，并在 package.json 文件中更新 version 字段。

description

description 字段用于描述包的简短说明。

类似于 HTML 网页 TDK 的 description，description 字段可以帮助用户快速了解包的作用。

keywords

keywords 字段用于描述包的关键字，它是一个字符串数组。

类似于 HTML 网页 TDK 的 keywords，keywords 字段可以帮助用户快速了解包的作用。

也有助于用户的检索。

homepage

homepage 字段用于指定包的主页。

以 axios 仓库为例：

{
  "homepage": "https://axios-http.com"
}

bugs

bugs 字段用于指定包的 issue 跟踪地址。

可以是一个 URL，也可以是一个邮箱地址。但推荐使用 URL。

{
  "bugs": {
    "url": "https://github.com/axios/axios/issues",
    "email" : "[email protected]"
  }
}

license

license 字段用于指定包的许可证。

license 字段可以是一个字符串，也可以是一个对象。

如果是一个字符串，那么它应该是一个有效的 SPDX 许可证标识符。

如果是一个对象，那么它应该包含 type 字段，用于指定许可证类型，以及 url 字段，用于指定许可证的 URL 地址。

{
  "license": "MIT"
}

{
  "license": {
    "type": "MIT",
    "url": "https://www.opensource.org/licenses/mit-license.php"
  }
}

author

author 字段用于指定包的作者。

author 字段可以是一个字符串，也可以是一个对象。

如果是一个字符串，那么它应该是一个有效的 name <email> (url) 格式的字符串。

{
  "author": "Barney Rubble <[email protected]> (http://barnyrubble.tumblr.com/)"
}

如果是一个对象，那么它应该包含 name 字段，用于指定作者名称，以及 email 字段和 url 字段，用于指定作者的邮箱地址和个人主页。

{
  "author": {
    "name" : "Barney Rubble",
    "email" : "[email protected]",
    "url" : "http://barnyrubble.tumblr.com/"
  }
}

contributors

contributors 字段用于指定包的贡献者。

contributors 字段是一个数组，数组中的每一项可以是一个字符串，也可以是一个对象。

contributors 与上述 author 字段的格式和使用方式相同。

区别在于 author 指定单个人，而 contributors 是数组，指代人的集合。

funding

funding 字段用于指定包的资助信息。

它包含 type 字段和 url 字段。

type 字段用于指定资助类型，url 字段用于指定资助地址。

{
  "funding": {
    "type" : "individual",
    "url" : "http://example.com/donate"
  },

  "funding": {
    "type" : "patreon",
    "url" : "https://www.patreon.com/my-account"
  },

  "funding": "http://example.com/donate",

  "funding": [
    {
      "type" : "individual",
      "url" : "http://example.com/donate"
    },
    "http://example.com/donateAlso",
    {
      "type" : "patreon",
      "url" : "https://www.patreon.com/my-account"
    }
  ]
}

files

可选的 files 字段是一个文件模式数组，用于描述当你的包作为依赖项安装时应包含的条目。

文件模式遵循类似于 .gitignore 的语法，但是与 .gitignore 的行为相反：包含一个文件、目录或通配符模式（、**/ 等）将使得在打包成 tarball 时该文件被包含在内。如果省略该字段，将默认为 ["*"]，表示包含所有文件。

无论文件数组中是否存在，某些特殊的文件和目录始终会被包含或排除（请参阅下文）。

你还可以在你的包的根目录或子目录中提供一个 .npmignore 文件，用于阻止文件被包含。

在包的根目录中，它不会覆盖 files 字段，但在子目录中会覆盖。

.npmignore 文件的工作原理与 .gitignore 文件类似。如果存在 .gitignore 文件而缺少 .npmignore 文件，则将使用 .gitignore 文件的内容。

使用 package.json#files 字段包含的文件无法通过 .npmignore 或 .gitignore 排除。

某些文件始终会被包含，不受设置的影响：

• 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 (use npm-shrinkwrap.json if you wish it to be published)

main

main 字段用于指定包的入口文件。

main 只能设置为字符串。

{
  "main": "./main.js"
}

如果未设置 main 字段，默认情况下它将是包根目录中的 index.js。

browser

browser 字段用于指定包在 browser 环境中的入口文件。

browser 字段可以设置为字符串或对象。

当设置为字符串时，它代表的是客户端浏览器环境下的入口文件。此时，会覆盖 main 字段的设置。

{
  "browser": "./browser.js"
}

当设置为对象时，它代表的是客户端浏览器环境下的文件映射解析。以 axios 库为例：

{
  "browser": {
    "./lib/adapters/http.js": "./lib/helpers/null.js",
    "./lib/platform/node/index.js": "./lib/platform/browser/index.js",
    "./lib/platform/node/classes/FormData.js": "./lib/helpers/null.js"
  }
}

上面的 ./lib/adapters/http.js 代表，在浏览器环境下将该文件映射为 ./lib/helpers/null.js 文件。后续两条配置同理。

关于 browser 字段的更多信息，请参考 package-browser-field-spec

:::tip 截止到这里，可能有一个疑问：设置 browser 字段后，代码是如何区分浏览器环境与 Node.js 环境的？

其实，可以将 browser 看做约定的准则、规范。环境的区分，依然要借助于打包器的实现。

譬如 webpack 中可以使用 target 字段来指定打包的目标环境。

当 target 设置为 web 时，webpack 会将 browser 字段的配置应用到打包结果中。

又譬如 rollup 插件 @rollup/plugin-node-resolve 也提供了对应的 browser 配置项。 :::

bin

bin 字段用于定义可执行命令（binaries）的路径和名称。

当使用 npm 安装指定包时，npm 会自动创建符号链接（symbolic link），将存在的 bin 字段中的可执行文件链接到 /usr/local/bin 目录中。

它可以设置为字符串，譬如：

{
  "name": "eslint",
  "bin": "./bin/eslint.js"
}

此时, 会采取 name 值作为命令名称。

如果需要设置多个命令，可以设置为对象，譬如：

{
  "name": "eslint",
  "bin": {
    "eslint": "./bin/eslint.js",
    "eslint-cli": "./bin/eslint-cli.js"
  }
}

此时，会采取 bin 对象的 key 作为命令名称。

所有的脚本 JavaScript 文件的头部需要声明 Shebang，以便 Node.js 能够正确地执行它们。

譬如：#!/usr/bin/env node。

:::tip /usr/bin/env 是一个常见的 Unix 和类 Unix 系统中的标准目录和命令。

它是一个可执行文件，通常用于在环境变量中查找并执行指定的命令。

当在命令行中执行 /usr/bin/env command 时，操作系统会搜索环境变量 $PATH 中列出的目录，以找到名为 command 的可执行文件，并使用找到的第一个匹配项来执行该命令。

例如，假设在环境变量 $PATH 中包含 /usr/local/bin 和 /usr/bin 这两个目录，并且在这两个目录下都存在名为 node 的可执行文件。

如果在命令行中执行 /usr/bin/env node，则操作系统将查找并执行 $PATH 中找到的第一个 node 可执行文件。

使用 /usr/bin/env 命令有助于提高脚本的可移植性，因为它使用环境变量来确定要使用的命令。这样，无论命令在文件系统中的确切路径是什么，都可以确保脚本在不同的系统和环境中都能正常执行。

在 Shebang 行中使用 /usr/bin/env 是一种常见的做法，如 #!/usr/bin/env python 或 #!/usr/bin/env node。

这样做可以确保在不同的系统中使用正确的解释器路径，而无需硬编码特定的解释器路径。 :::

repository

repository 字段用于指定包的仓库地址。

repository 字段可以是一个字符串，也可以是一个对象。

譬如：

{
  "repository": "eslint/eslint",

  "repository": "https://github.com/axios/axios.git"
}

其中，eslint/eslint 是一个简写，表示包的存储库位于 GitHub 上的 eslint 组织下的 eslint 存储库。

它等价于 https://github.com/eslint/eslint.git。

如果是一个对象，那么它应该包含 type 字段，用于指定仓库类型，以及 url 字段，用于指定仓库地址。

{
  "repository": {
    "type": "git",
    "url": "https://github.com/eslint/eslint.git"
  }
}

type 值可以设置为 git、svn、mercurial 以及 cvs 等等。

需要注意的是，type 属性并不影响包的实际行为或安装过程。

type 仅用于提供关于包的版本控制存储库的元数据，以便用户和开发者能够方便地访问和查找相关信息。

如果这个包的 package.json 文件并不在根目录，譬如 monorepo 形式的仓库，那么可以利用 directory 字段进一步指定：

{
  "repository": {
    "type": "git",
    "url": "https://github.com/facebook/react.git",
    "directory": "packages/react-dom"
  }
}

scripts

scripts 字段用于指定一系列的脚本命令。

scripts 字段是一个对象，对象的每一个 key 都是一个脚本命令的名称，value 是该脚本命令的执行命令。

譬如：

{
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  }
}

config

config 字段用于指定自定义的配置信息。

譬如：

{
  "config": {
    "apiEndpoint": "https://api.example.com",
    "port": "8080",
    "timeout": 5000
  }
}

当在 package.json 中定义了上述信息后，可以通过 process.env 来访问这些信息。

console.log(process.env.npm_package_config_apiEndpoint)

console.log(process.env.npm_package_config_port)

console.log(process.env.npm_package_config_timeout)

dependencies

dependencies 字段用于指定包的依赖项。

譬如：

{
  "dependencies": {
    "axios": "^0.21.1",
    "chalk": "^4.1.0"
  }
}

devDependencies

devDependencies 字段用于指定包的开发依赖项。

当我们的包要提供给其他人使用时，我们需要将项目中的相关开发依赖声明到 devDependencies 字段中。

这样，别人在利用 npm install 安装我们的包时，就不会安装这些多余的开发依赖了。

譬如：

{
  "devDependencies": {
    "eslint": "^7.18.0",
    "eslint-config-standard": "^16.0.2",
    "eslint-plugin-import": "^2.22.1",
    "eslint-plugin-node": "^11.1.0",
    "eslint-plugin-promise": "^4.3.1",
    "eslint-plugin-standard": "^5.0.0"
  }
}

peerDependencies

peerDependencies 字段用于指定包的对等依赖项。

假设我们的包依赖于特定版本的第三方库，那么为了保证兼容性，可以将其声明为对等依赖项。

譬如：

{
  "peerDependencies": {
    "vue": "^2.0",
  }
}

上述配置代表，我们的项目只能依赖于 vue 的 2.x 版本。

当我们安装了不符合要求的 vue 版本时，npm 会给出警告。

:::tip 在 [email protected] 至 [email protected]，npm install 不会安装 peerDependencies。

在 [email protected] 及以上版本，npm install 会安装 peerDependencies。

另外，笔者测试了本机上的 [email protected] 版本执行 yarn 时，不会安装 peerDependencies。 :::

peerDependenciesMeta

peerDependenciesMeta 字段用于指定包的对等依赖项的元数据。

目前，peerDependenciesMeta 字段只支持 optional 属性。

譬如，我们创建了 module-a：

{
  "peerDependencies": { 
    "winston": "> 1.0.0 <= 1.2.10",
    "foo": "~2.3.0"
  },
  "peerDependenciesMeta": {
    "winston": {
      "optional": true
    }
  }
}

那么，在利用 npm install 安装 module-a 时，如果 winston 的依赖不满足 > 1.0.0 <= 1.2.10，此时 npm 不会警告。

因为，此处设置了 peerDependenciesMeta 中的 winston 的 optional 为 true。

但是，如果 foo 的依赖不满足 ~2.3.0，此时 npm 会警告。

bundledDependencies

bundledDependencies 字段用于指定包的捆绑依赖项。

捆绑依赖项是指在项目打包过程中将依赖项的完整内容包含在项目中，而不是通过安装依赖项来引用它们。

这在某些情况下是有用的，例如当你的应用程序需要在某些环境中运行（如无网络连接的服务器或离线应用程序）。

bundleDependencies 字段是一个字符串数组，包含了项目的捆绑依赖项的名称。

譬如：

{
  "bundledDependencies": [
    "jquery",
    "vue"
  ]
}

当你运行 npm pack 命令时，npm 将会包含这些依赖项的完整内容，并将它们打包到生成的 .tgz 文件中。

在使用这个打包文件部署应用程序时，捆绑的依赖项将被解压并包含在项目中。

需要注意的是，bundleDependencies 是一个过时的字段，而在现代的 Node.js 项目中，更常用的方法是使用工具如 webpack 或 Parcel 来打包应用程序，并通过依赖项的引用来管理依赖关系。

optionalDependencies

optionalDependencies 字段用于指定包的可选依赖项。

可选依赖项是指在安装项目的依赖项时，如果遇到可选依赖项无法安装或编译的情况，不会导致整个安装过程失败。

换句话说，可选依赖项是对项目功能的补充或增强，但不是必需的。

optionalDependencies 字段是一个对象，其中键是可选依赖项的名称，值是版本范围或 URL。

譬如：

{
  "optionalDependencies": {
    "eslint": "^7.18.0",
  }
}

当运行 npm install 命令安装项目的依赖项时，NPM 会尝试安装这些可选依赖项。

如果可选依赖项无法安装成功，NPM 将继续安装其他依赖项，并输出警告消息指示哪些可选依赖项未被安装。

可选依赖项在某些情况下很有用，例如当你的项目需要与某个特定的库或插件进行集成，但该库或插件并非必需时。

在这种情况下，你可以将其列为可选依赖项，并在项目中通过条件逻辑或动态加载来使用它们。

需要注意的是，可选依赖项的使用应慎重。在编写代码时，你应该始终考虑可选依赖项的缺失，并编写适当的逻辑来处理它们不存在的情况，以确保项目的健壮性和可移植性。

engines

engines 字段用于指定项目运行的 Node.js 版本范围。

这对于确保你的项目在特定的 Node.js 版本上能够正常运行非常有用，因为不同的 Node.js 版本可能具有不同的语法和功能特性。

engines 字段是一个对象，其中可以包含以下键：

• node：指定你的项目所需的最低 Node.js 版本或版本范围。你可以使用类似 >=10.0.0 的语法来指定范围。

• npm：指定你的项目所需的最低 npm 版本或版本范围。

譬如：

{
  "name": "my-project",
  "version": "1.0.0",
  "engines": {
    "node": ">=12.0.0",
    "npm": ">=6.0.0"
  }
}

在上述示例中，engines 字段指定了项目所需的最低 Node.js 版本为 >=12.0.0 ，以及所需的最低 npm 版本为 >=6.0.0。

当其他人尝试安装或使用你的项目时，npm 会检查他们的 Node.js 和 npm 版本是否满足 engines 字段中指定的要求。

如果不满足要求，npm 会显示警告消息，提醒他们升级 Node.js 或 npm 以满足项目的要求。

:::tip 默认情况下，本地环境不满足 engines 设置时，npm 会显示警告消息，但不会阻止安装或使用项目。

如果想要阻止，那么本地的 npm 需要设置 engine-strict 为 true：

npm config set engine-strict=true

:::

os

os 字段用于指定项目运行的操作系统。

os 字段是一个字符串数组，包含了项目所需的操作系统名称。

譬如：

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

在上述示例中，os 字段指定了项目所需的操作系统为 darwin 和 linux，非 win32。

当其他人尝试安装或使用你的项目时，npm 会检查他们的操作系统是否满足 os 字段中指定的要求。

如果不满足要求，npm 会显示警告消息，提醒他们使用支持的操作系统。

cpu

cpu 字段用于指定项目运行的 CPU 架构。

cpu 字段是一个字符串数组，包含了项目所需的 CPU 架构名称。

譬如：

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

在上述示例中，cpu 字段指定了项目所需的 CPU 架构为 x64 和 ia32，非 arm。

当其他人尝试安装或使用你的项目时，npm 会检查他们的 CPU 架构是否满足 cpu 字段中指定的要求。

如果不满足要求，npm 会显示警告消息，提醒他们使用支持的 CPU 架构。

private

private 字段用于指定包是否为私有包。

private 字段是一个布尔值，如果设置为 true，则表示该包为私有包，否则为公共包。

譬如：

{
  "private": true
}

当设置为 true 时，npm 会在发布时给出警告。

publishConfig

publishConfig 字段用于指定发布包时的配置信息。

publishConfig 字段是一个对象，其中可以包含以下键：

• registry：指定发布包时的仓库地址。
• access：指定发布包时的访问级别，可以设置为 public 表示公开访问，或者 restricted 表示限制访问。
• tag：指定发布包时的标签。
• otp：指定发布包时的 OTP。

npm 默认将 @scope/package 视作 private 包。

因此，如果你想发布 @scope/package 包，那么需要设置 publishConfig 字段中的 access 属性为 public。

譬如：

{
  "name": "@scope/package",
  "version": "1.0.0",
  "publishConfig": {
    "access": "public",
    "registry": "https://registry.npmjs.org/"
  }
}

workspaces

exports

exports 字段用于指定包的导出方式。

它与 main 字段类似，但是提供了更多的灵活性。可以将其看做高版本 Node.js 的 main 字段。

但 exports 只在较高版本的 Node.js 才支持，因此为了保证 Node.js@12 及以下版本的兼容，Node.js 通常依然会设置 main 字段。

譬如，假设有 [email protected] 有以下设置：

{
  "name": "only-for-npm-test",
  "version": "1.0.2",
  "main": "index.js",
  "exports": {
    "./main.js": "./lib/main.js"
  }
}

假设我们在此 Node.js@8 版本的基础上，创建了一个 test.js：

const result = require('only-for-npm-test')

console.log(result)

那么，此时执行 test.js 文件，是能够正常执行的。因为 Node.js@12 及以下版本不支持 exports 字段, 支持 main 字段。

让我们把 Node.js 切换到 v16 版本，此时执行 test.js 文件，会报错：

[ERR_PACKAGE_PATH_NOT_EXPORTED]: No "exports" main defined

此时，需要将代码修改为：

const result = require('only-for-npm-test/main.js')

console.log(result)

关于 exports 属性的更多介绍，可以参考packages_package_entry_points。

:::tip 当 package.json 中的 exports 和 main 字段同时存在时，exports 的优先级更高，会覆盖 main 字段。

而在使用 require('only-for-npm-test/main.js')，要注意 main.js 相对 only-for-npm-test 的路径是 ./main.js。

因此，在设置 exports 时，必须设置的是 ./main.js 而非 main.js。

即：

{
  "exports": {
    "./main.js": "./lib/main.js"
  }
}

而非：

{
  "exports": {
    "main.js": "./lib/main.js"
  }
}

否则，会报错：

[ERR_PACKAGE_PATH_NOT_EXPORTED]:Package subpath './main.js' is not defined by "exports" :::

4.package-lock.json

package-lock.json 是一个用于记录项目依赖项及其版本信息的文件，用于保证在不同环境中安装相同的依赖项版本，从而提供更一致和可重复的构建过程。

package-lock.json 会在使用 npm install 命令时自动生成或更新，通常不需要手动编辑或修改。

当运行 npm install 命令时，npm 会检查你的 package.json 文件中的依赖项，并根据这些依赖项的版本解析出一个具体的依赖关系树。

然后，npm 会将解析出的依赖关系写入 package-lock.json 文件中，包括每个依赖项的确切版本号以及其依赖项的版本范围。

package-lock.json 的主要目的是锁定项目的依赖项版本，以便在将来的安装过程中使用相同的版本。

这样可以确保不同开发者或不同的环境都安装了相同的依赖项版本，从而避免因为依赖项版本不一致而引发的问题。

package-lock.json 还包含一些其他的信息，如依赖项的下载地址、校验和以及安装路径等。

当你分享你的项目时，推荐将 package-lock.json 一同提交到版本控制系统中，以确保其他人在安装你的项目时能够得到相同的依赖项版本。

:::tip 简而言之，由于 package.json 中的 dependencies 是基于 semver 的，因此在安装依赖项时，npm 会根据 semver 规则来解析依赖项的版本范围，然后安装符合要求的最新版本。

这样，就可能导致不同的开发者或不同的环境安装了不同的依赖项版本，从而引发一些问题。

因此，package-lock.json 的主要目的是锁定项目的依赖项版本，以便在将来的安装过程中使用相同的版本。 :::

5.Sematic Versioning

semver 是 Semantic Versioning 的缩写，意为语义化版本。

semver 是一种规范，用于规范化版本号，以便开发者能够根据版本号来推断出依赖项的兼容性。

5.1.语义化版本

semver 的版本号由三个数字组成，分别是 major、minor 和 patch。

其中，major 表示主版本号，minor 表示次版本号，patch 表示补丁版本号。

譬如 1.0.0、2.1.0、3.0.1 等等。

当你的项目发生了不兼容的改变时，需要升级 major 版本号。

当你的项目增加了新的功能时，需要升级 minor 版本号。

当你的项目修复了一些 bug 时，需要升级 patch 版本号。

5.2.版本范围

semver 规范还定义了一些版本范围，用于指定依赖项的版本范围。

譬如 ^1.0.0、~2.1.0、>=3.0.1 等等。

其中，^ 表示 major 版本号不变，minor 和 patch 版本号可以升级。

~ 表示 major 和 minor 版本号不变，patch 版本号可以升级。

>= 表示 major、minor 和 patch 版本号都可以升级。