Skip to content

鼓励作者:欢迎 star 或打赏犒劳

package.json

描述配置

name required

string 项目名称,发布到 npm 中的唯一标识

ts
const pkgNameReg = ^(?:@[a-z0-9-*~][a-z0-9-*._~]*/)?[a-z0-9-~][a-z0-9-._~]*$

version required

string 版本号,遵循 语义化版本号,使用 npm version 管理

description

string 项目描述

keywords

Array<string> 项目关键词, 作用类似于 description

homepage

string 项目主页,一般是项目网站或者 GitHub 地址

repository

string | { type: string; url: string } 项目仓库

bugs

string | { url: string; email?: string }

一般是 issue 地址。存在时可以通过 npm bugs 打开对应地址

author, contributors

string 作者或贡献者信息

json
{
  "author": "maomao1996 <1714487678@qq.com> (https://github.com/maomao1996)"
}

{
  "contributors": [
    {
      "name" : "maomao1996",
      "email" : "1714487678@qq.com",
      "url" : "https://github.com/maomao1996"
    },
    {
      "name" : "maomao",
      "email" : "1714487678@qq.com",
      "url" : "https://github.com/maomao1996"
    }
  ]
}

licenses

  • string recommend
  • string | { type: string; url: string } | Array<{ type: string; url: string }>

详见 https://spdx.org/licenses/

json
{
  "license" : {
    "type" : "ISC",
    "url" : "https://opensource.org/licenses/ISC"
  }
}
// or
{
  "licenses" : [
    {
      "type": "MIT",
      "url": "https://www.opensource.org/licenses/mit-license.php"
    },
    {
      "type": "Apache-2.0",
      "url": "https://opensource.org/licenses/apache2.0.php"
    }
  ]
}
// recommend
{
  "licenses": "MIT"
}

文件配置

type

'commonjs' | 'module' 表明包使用的模块语法( Node@14 以上版本支持 ES Module

  • 默认为 commonjs, 对于 mjs 后缀名文件采用 ESM 语法解析

  • 设置为 module 时,对于 cjs 后缀名文件采用 commonjs 语法解析

bin

string | { ${binName}: ${binFilePath} } 声明包的脚本文件

脚本文件一般在文件头以 SheBang 声明运行脚本的语言

sh
npm install demo -g

d
# log: Npm is COOL
js
#!/usr/bin/env node

console.log('Npm is COOL')
json
{
  "name": "demo",
  "bin": {
    "d": "./bin/demo.js"
  }
}
sh
.
├── bin
   └── demo.js
└── package.json

files

Array<string> 指明将此项目作为依赖包安装时包含的文件,默认为排除以下文件的全部内容:

  • .git
  • CVS
  • .svn
  • .hg
  • .lock-wscript
  • .wafpickle-N
  • .*.swp
  • .DS_Store
  • ._*
  • npm-debug.log
  • .npmrc
  • node_modules
  • config.gypi
  • *.orig
  • package.json / npm-shrinkwrap.json

TIP

files 字段作用类似的还有 .npmignore.gitignore

files 类似于白名单,往往产物内容更少更方便。而 ignore 文件类似于黑名单,需要开发者持续维护

types

string => filePath 声明此项目的 TypeScript 类型文件

TIP

  • typestypings 意义完全相同,可替换使用
  • 当主声明文件命名为 index.d.ts,并且位于包的根目录与 index.js 同级,则可以省略 types 字段,但建议保持良好的声明式习惯

参阅 TypeScript | Docs

main

string 标准化的工具包主入口

默认为 index.js ,主要用于 Node.jscjs 模块

js
const foo = require('foo') // => from "main" field
// foo => { value: 1 }
js
// foo.cjs
module.exports = {
  value: 1,
}
json
// package.json
{
  "main": "./foo.cjs"
}

browser

string 工具包主入口

当项目仅服务于浏览器端,则应采用此字段代替 main 字段

html
<script src="foo.js"></script>

module

string 工具包主入口

非官方支持的字段,基本上是 WebpackRollup 等打包工具为支持 ES Module 而约定的字段

exports

Record<string, string | Exports> 最新标准的导出接口 recommend

为工具包主入口及其语义版本升级提供了更可靠的保证,支持多模块、多环境、子路径等定义形式。

json
{
  "exports": {
    ".": {
      "node-addons": "", // for C++ plugins
      "node": "foo-node.js", // Node.js environment,一般不需要
      "import": "foo.mjs", // for import/import()
      "require": "foo.cjs", // for require()
      "default": "" // 兜底
    },
    // 子模块路径 foo/bar.js
    "./bar.js": {
      "import": "./bar.mjs",
      "require": "./bar.cjs"
    },
    // for TypeScript
    "types": {},
    // for browser
    "browser": {},
    // for deno
    "deno": {},
    // dev environment
    "development": {},
    // prod environment
    "production": {}
  }
}

TIP

  • 优先使用 exports 并配合 main 等字段做兼容配置
json
{
  "main": "foo.cjs",
  "module": "foo.mjs",
  "browser": "foo.umd.js",
  "types": "foo.d.ts",
  "exports": {
    ".": {
      "import": "foo.mjs",
      "require": "foo.cjs",
      "browser": "foo.umd.js",
      "types": "foo.d.ts"
    }
  }
}

workspaces

Array<string> 声明多包项目 monorepo 的子包路径 详见 workspaces | npm Docs

依赖配置

{pkgName<string>: pkgVersion<string>} 项目依赖包映射表

常见依赖包版本遵循 语义化版本号,并根据声明语法供 lockfile 匹配:

  • ^:仅固定 major 大版本,匹配 minorpatch 版本
  • ~:固定 majorminor 版本,仅匹配 patch 补丁版本

其余版本范围详见文档 dependencies

通过 npm link 等生成的本地包路径详见 local-path 文档

dependencies

--save, -S 不区分运行环境等,任何情况都需要安装的依赖项

devDependencies

--save-dev, -D 仅在开发环境安装的依赖项

peerDependencies

--save-peer 对等依赖项

比如 vue-routervuex 都是基于 vue@2.x 的响应式 API 构建的依赖库(插件),但在构建 vue-routervuex 产物时,作者并不想将 vue 包含进去,即可将 vue 声明为 peerDependencies .

TIP

  • >=npm@7 默认安装 peerDependencies
  • 3<npm<=6 用户需要自行管理 peerDependencies

peerDependenciesMeta

当用户安装了该项目但未安装 peerDependencies 时,此字段提供对应的处理声明:

json
// vue-router
{
  "peerDependencies": {
    "vue": "^2.6.0"
  },
  "peerDependenciesMeta": {
    "vue": {
      "optional": true // 若使用 `vue-router` 时未安装 `vue` 依赖,那么将 `vue` 视为可选依赖
    }
  }
}

optionalDependencies

--save-optional, -O 可选的依赖项,即使安装此类型依赖失败,也不会影响功能使用 一般由开发者提供兼容处理

TIP

比如在使用 chokidarOSX 系统使用原生的 fsevents 进行文件监听处理,但在 Linux (主要是 mac) 上安装此依赖时经常出现 fsevents 相关的报错信息。此时可以添加参数忽略此依赖进行安装:

  • npm/pnpm install --no-optional

  • yarn install --ignore-optional

bundleDependencies

Array<string> 捆绑依赖项,可通过 npm pack 将声明的捆绑依赖打包进项目压缩包中

overrides

Record<string, string> 针对特定依赖项进行按需重写,支持嵌套、限定范围

json
{
  "overrides": {
    "foo": "1.0.0",
    // or
    "baz": {
      "bar": {
        "foo": "1.0.0"
      }
    }
  }
}

脚本配置

scripts

Record<string, string> 带有以下默认生命周期的脚本命令: <pre> | <post>

  • install
  • uninstall
  • start
  • restart
  • stop
  • test
  • pack
  • publish
  • 自定义脚本命令

特殊的 prepareprepublishOnlyscripts 文档

TIP

在 pnpm@6 与 yarn2 中, preinstall 将在 install 后执行,而不是在 install 之前

为此 pnpm 提供了 pnpm:devPreinstall 钩子以兼容开发者的使用习惯

config

Record<string, string> process.env 配置命令行的环境变量

js
#!/usr/bin/env node

console.log(process.env.npm_package_config_port) // 8732
console.log(process.env.npm_package_config_foo) // bar
json
{
  "scripts": {
    "variable": "node main.js"
  },
  "config": {
    "port": "8732",
    "foo": "bar"
  }
}

packageManager

string 用于指明项目使用的包管理工具,无需第三方工具即可保障团队包管理工具的统一,具体见 packagemanager | Docs

ts
const pkgManagerReg = (npm|pnpm|yarn)@\d+\.\d+\.\d+(-.+)?

发布配置

private

boolean 指明包私有,避免被 npm publish 发布

publishConfig

Record<string, string> 发布配置,详见config | npm Docs

系统配置

engines

Record<'node'|'npm', string> 指明该项目运行的平台

  • 指明项目所需 node 版本
json
{
  "engines": {
    "node": ">=14 <18"
  }
}
  • 指明安装包所需 npm 版本
json
{
  "engines": {
    "npm": "~5.2.0" // npx version
  }
}

os

Array<string> 基于 process.platform 运行项目的操作系统黑白名单:

前缀 ! 表示黑名单

json
{
  /* 白名单 */
  "os": ["darwin", "linux"]

  /* 黑名单 */
  {
    "os": ["!win32"]
  }
}

cpu

Array<string> 基于 process.arch 设置 CPU 架构的黑名单和白名单:

前缀 ! 表示黑名单

json
{
  /* 白名单 */
  "cpu": ["x64", "ia32"]

  /* 黑名单 */
  {
    "cpu": ["!arm"]
  }
}

第三方配置

sideEffects

boolean | Array<string => filePath> 声明存在副作用的模块,用于 Webpack 等打包工具的导出优化

对于模块是否有副作用的定义,基本是指开发者在设计时是否产生了副作用,而不必关心经过打包工具处理后的最终产物。

unpkg

string => filePath 在发布到 npm 后,可以使用此字段为项目对应的文件开启 CDN 服务,默认为 main

TIP

参阅 unpkg | docs

jsdelivr

string => filePath 类似于 unpkg

cosmiconfig

基于 cosmiconfig 实现的相关配置仅在此简单罗列常用工具

如有转载或 CV 的请标注本站原文地址