package.json 查漏补缺——配置详解

下面的内容基本都是从官方文档上整理过来的。介绍一些比较重要的字段，不太常见的就不写了。详细内容可以查看官方文档。

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 的详细内容，可以看官方文档