package.json 字段说明：参数字段详解

太微2026-04-13工程化npm package.json Node.js 依赖

`package.json` 字段说明：参数字段详解

package.json 是 npm / pnpm / yarn 等包管理器识别的项目清单：描述包名、版本、入口、脚本、依赖与发布行为。字段是否生效取决于工具链（例如 exports 由 Node 与打包器解析，scripts 由 npm run 执行）。下面按用途分组说明常用字段；未列出的字段可参考 npm 官方文档 package.jsonopen in new window。

1. 基础标识与描述

字段	类型	含义与注意
`name`	string	包名。发布到 npm 时需符合命名规则open in new window（小写、可用 `-`、scoped 形如 `@scope/name`）。应用项目可随意，但建议与仓库名一致。
`version`	string	语义化版本（semver），形如 `1.2.3`。`npm version` 会维护该字段；未发布的应用常用 `0.0.1` 或 `1.0.0` 占位。
`description`	string	简短描述，npm 搜索页展示用。
`keywords`	string[]	关键词，便于检索。
`private`	boolean	为 `true` 时禁止误发布到公共 registry（`npm publish` 会拒绝），适合业务应用仓库。
`license`	string	SPDX 许可证标识，如 `MIT`、`Apache-2.0`；闭源可用 `UNLICENSED` 或自定义协议说明（配合 `LICENSE` 文件）。
`author`	string 或 object	作者；可为 `"Name <email> (url)"` 或 `{ "name", "email", "url" }`。
`contributors`	array	贡献者列表，元素格式同 `author`。

2. 仓库、主页与问题反馈

字段	类型	含义
`repository`	string 或 object	源码地址。对象形式常见：`{ "type": "git", "url": "..." }`。
`homepage`	string	项目主页文档地址。
`bugs`	string 或 object	提 Issue 的地址，如 `{ "url": "https://github.com/org/repo/issues" }`。

3. 模块入口与解析（Node / 打包器）

字段	类型	含义与注意
`type`	string	`"module"` 时，`.js` 文件在 Node 中按 ESM 解析；缺省为 CommonJS。与 `"module"` 并列时注意工具链是否支持。
`main`	string	CommonJS 主入口（历史最通用），如 `index.js` 或 `dist/index.cjs`。
`module`	string	部分工具识别的 ESM 入口（非官方标准字段，但广泛使用），如 `dist/index.mjs`。
`browser`	string 或 object	在浏览器打包时替换 `main` 的入口，供 Webpack 等解析。
`exports`	object 或 string	推荐的入口声明（Node 12+ 条件导出、子路径封装）。可区分 `import` / `require`、开发/生产、不同环境。优先级高于 `main`。
`types` / `typings`	string	TypeScript 类型声明入口（如 `dist/index.d.ts`）。

exports 简例（条件导出）：

{
  "exports": {
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs",
      "types": "./dist/index.d.ts"
    },
    "./package.json": "./package.json"
  }
}

4. `scripts`：可执行脚本

要点	说明
结构	键为脚本名，值为 shell 命令字符串。
运行	`npm run <name>`；`start`、`test`、`stop` 等可省略 `run`（`npm start`）。
生命周期钩子	如 `preinstall`、`postinstall`、`prepare`（安装依赖后执行，常用于构建 git 依赖或 husky）。
环境变量	可读取 `npm_package_*` 等 npm 注入变量；跨平台命令建议用 `cross-env` 等。

常见脚本名约定：dev、build、preview、lint、test，无强制，团队统一即可。

5. 依赖字段

字段	用途
`dependencies`	生产依赖：运行时需要的包（部署或用户安装你的包时会装）。
`devDependencies`	开发依赖：仅本地开发、测试、构建需要（如 ESLint、Vitest）。
`peerDependencies`	同伴依赖：不随你的包安装，要求宿主环境提供指定版本（如插件要求 `vue@^3`）。
`peerDependenciesMeta`	为某个 peer 标记 `optional": true`，缺失时不报错（可选 peer）。
`optionalDependencies`	安装失败时不导致整体失败的可选原生模块等。
`bundledDependencies`	发布时打进 tarball 的包名列表（较少用）。

版本范围常用符号：^ 兼容次版本、~ 兼容补丁、* / latest 慎用。具体语义以 semver 与 npm 文档为准。

6. 发布与包内容

字段	类型	含义
`files`	string[]	白名单：发布到 npm 时包含的文件/目录（仍始终包含 `package.json`、`README`、`LICENSE` 等）。未设置时默认规则见 npm 文档。
`bin`	string 或 object	命令行可执行文件映射；全局安装时可在 PATH 中提供命令。
`directories`	object	提示性目录说明，如 `{"lib": "./lib"}`；实际以 `files` / `.npmignore` 为准。

7. 运行环境与平台

字段	类型	含义
`engines`	object	要求的 Node / npm 版本，如 `{ "node": ">=18" }`。不匹配的包管理器可能给出 warning（`engine-strict` 可改为错误）。
`os`	string[]	适用的操作系统（如 `["darwin", "linux"]`），不匹配时跳过可选安装或警告。
`cpu`	string[]	适用的 CPU 架构。

8. Monorepo 与包管理器扩展

字段	含义
`workspaces`	npm / yarn 的 workspace 根配置，值为子包路径数组或 glob，用于 monorepo。
`packageManager`	Corepack 使用，如 `"pnpm@9.0.0"`，锁定默认包管理器版本。

pnpm 的 pnpm.overrides、npm 的 overrides、yarn 的 resolutions 用于统一子依赖版本，写在 package.json 顶层，字段名随工具而异。

9. 其它常见字段

字段	含义
`sideEffects`	`false` 或路径数组，帮助打包器做 tree-shaking（声明无副作用的文件可被安全剔除）。
`config`	在 `package.json` 内保存可被子进程读取的配置（如 `port`），通过 `npm_package_config_*` 暴露。
`funding`	资助信息 URL 或对象，供 `npm fund` 展示。

10. 最小可读示例

{
  "name": "my-app",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "description": "示例应用",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview"
  },
  "dependencies": {
    "vue": "^3.5.0"
  },
  "devDependencies": {
    "vite": "^6.0.0"
  },
  "engines": {
    "node": ">=18"
  }
}

11. 最大示例（综合字段演示）

下面是一份刻意堆满字段的「可发布类库」示例，用于对照上文各节；并非真实项目模板——实际仓库往往只保留其中一部分，且 monorepo 根 与 可发包 不会共用同一套字段（根目录常见 private + workspaces，通常不再写 main / exports）。

{
  "name": "@demo/example-lib",
  "version": "2.4.0",
  "description": "教学用：尽量展示 package.json 常见顶层字段；发布前请按项目裁剪。",
  "keywords": ["demo", "typescript", "library"],
  "homepage": "https://github.com/org/repo#readme",
  "bugs": {
    "url": "https://github.com/org/repo/issues",
    "email": "bugs@example.com"
  },
  "repository": {
    "type": "git",
    "url": "git+https://github.com/org/repo.git",
    "directory": "packages/example-lib"
  },
  "license": "MIT",
  "author": {
    "name": "Demo Author",
    "email": "author@example.com",
    "url": "https://example.com"
  },
  "contributors": [
    "Contributor One <c1@example.com> (https://example.com/c1)"
  ],
  "funding": [
    {
      "type": "github",
      "url": "https://github.com/sponsors/org"
    },
    "https://opencollective.com/org"
  ],
  "type": "module",
  "main": "./dist/index.cjs",
  "module": "./dist/index.mjs",
  "types": "./dist/index.d.ts",
  "browser": "./dist/browser.js",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs",
      "default": "./dist/index.mjs"
    },
    "./sub": "./dist/sub.js",
    "./package.json": "./package.json"
  },
  "sideEffects": ["./dist/polyfill.js"],
  "files": ["dist", "README.md", "LICENSE"],
  "bin": {
    "cli-demo": "./dist/cli.mjs"
  },
  "directories": {
    "lib": "dist",
    "test": "tests"
  },
  "scripts": {
    "prepare": "npm run build",
    "prepublishOnly": "npm test && npm run build",
    "build": "tsup",
    "dev": "tsup --watch",
    "test": "vitest run",
    "lint": "eslint ."
  },
  "dependencies": {
    "lodash-es": "^4.17.21"
  },
  "devDependencies": {
    "typescript": "^5.7.0",
    "vitest": "^3.0.0",
    "tsup": "^8.0.0",
    "eslint": "^9.0.0"
  },
  "peerDependencies": {
    "react": ">=18.0.0"
  },
  "peerDependenciesMeta": {
    "react": {
      "optional": true
    }
  },
  "optionalDependencies": {
    "fsevents": "^2.3.3"
  },
  "bundledDependencies": ["some-vendored-pkg"],
  "engines": {
    "node": ">=18.0.0",
    "npm": ">=9.0.0"
  },
  "os": ["darwin", "linux", "win32"],
  "cpu": ["x64", "arm64"],
  "config": {
    "port": "3000"
  },
  "overrides": {
    "semver": "^7.6.0"
  }
}

字段注解（类库示例）

字段	注解
`name`	带作用域的包名（`@scope/pkg`），发布后在 registry 中的唯一标识；未发布仅作本地名。
`version`	semver，发版时与 git tag / CHANGELOG 对齐；`npm version` 可自动递增。
`description`	一句话说明，影响 npm 搜索与包页摘要。
`keywords`	检索标签，帮助用户发现包。
`homepage`	文档站或 README 外链，多为仓库首页或文档根 URL。
`bugs`	提 Issue 的入口：`url` 指向 Issues 页，`email` 为备用联系（可选）。
`repository`	源码位置；`directory` 在 monorepo 子包中标注相对仓库根的路径，便于 npm/GitHub 跳转。
`license`	SPDX 短名（如 `MIT`）；与仓库根 `LICENSE` 文件一致。
`author`	主要维护者；字符串与对象两种写法等价，对象便于结构化展示。
`contributors`	其他贡献者列表，格式与 `author` 类似。
`funding`	资助渠道，支持字符串 URL 或 `{ type, url }`；`npm fund` 会列出。
`type`	为 `module` 时，未标注的 `.js` 在 Node 中按 ESM 解析。
`main`	CommonJS 默认入口，老工具与 `require()` 优先看它。
`module`	部分打包器识别的 ESM 入口（非 Node 官方字段，但生态常用）。
`types`	TypeScript 声明入口；与 `exports` 里的 `types` 条件配合更佳。
`browser`	浏览器打包时替换 `main` 的入口（如避开 Node 专用 API）。
`exports`	优先级高于 `main`；`.` 为主入口，`import` / `require` / `types` 分流；`./sub` 为子路径导出；暴露 `./package.json` 便于工具读取元数据。
`sideEffects`	声明有副作用的文件（如改全局）；其余可更安全地做 tree-shaking。
`files`	发布白名单；未列出的源码若需带上须写进此处（或依赖 npm 默认包含规则）。
`bin`	全局/本地 `npx` 时的命令名 → 可执行文件映射。
`directories`	仅文档性提示，不参与打包逻辑；真实仍以 `files`、`.npmignore` 为准。
`scripts`	`prepare` 在 `npm install` 后常跑构建；`prepublishOnly` 在 `npm publish` 前跑测试与构建，避免脏包。
`dependencies`	运行时必装依赖，随包一起装到使用者 `node_modules`。
`devDependencies`	仅开发、测试、构建；不会作为你的包的传递依赖发布给下游（除非被打进产物）。
`peerDependencies`	要求宿主提供（如插件要求 `react`），由使用者安装，避免重复装多份。
`peerDependenciesMeta`	将某 peer 标为 `optional`，未安装时 npm 不报错（功能降级场景）。
`optionalDependencies`	装失败（如无对应平台二进制）时不阻断整体安装，代码内需 `try/catch` 或存在性判断。
`bundledDependencies`	发布时把列出的包打进 tarball，用于锁定内部工具或规避 hoisting 问题（慎用体积）。
`engines`	声明 Node / npm 最低版本；CI 与部署应与此一致。
`os` / `cpu`	可选的平台过滤；不匹配时安装可能跳过或警告（视包管理器策略）。
`config`	可通过 `npm_package_config_port` 等形式注入脚本；适合团队约定默认端口等。
`overrides`	npm 强制锁定嵌套依赖版本，解决安全或重复安装问题；与 `pnpm.overrides` 二选一或分层由规范决定。

monorepo 根常见写法（与上表「类库」二选一，勿简单合并）：

{
  "name": "my-monorepo",
  "private": true,
  "version": "0.0.0",
  "workspaces": ["packages/*", "apps/*"],
  "packageManager": "pnpm@9.14.0",
  "scripts": {
    "build": "pnpm -r run build",
    "test": "pnpm -r run test"
  },
  "devDependencies": {
    "typescript": "^5.7.0"
  }
}

字段注解（monorepo 根）

字段	注解
`name`	仓库「壳」名称，一般不单独发布；版本常固定 `0.0.0` 或仅作内部标记。
`private`	`true` 禁止误执行 `npm publish` 把整个根目录发出去。
`version`	根目录版本可不参与发版；若用 Changesets 等工具则可能统一管理。
`workspaces`	声明子包路径（glob），npm / yarn / pnpm 均识别，用于链接本地包与统一安装。
`packageManager`	配合 Corepack 锁定 pnpm/yarn 主版本，减少「每人版本不一致」。
`scripts`	常用 `-r` / `--recursive` 在所有 workspace 包上执行 `build`、`test`。
`devDependencies`	根目录可放公共开发依赖（如 TS、ESLint），子包再声明各自特有依赖。

使用 pnpm 时可在同一份 package.json 增加 pnpm 字段（与 npm 的 overrides 择一或分层使用，以团队规范为准）：

{
  "pnpm": {
    "overrides": {
      "semver": "^7.6.0"
    }
  }
}

字段注解（pnpm 补充）

字段	注解
`pnpm.overrides`	与 npm `overrides` 类似，在 pnpm 安装树里强制某依赖（或嵌套路径）的版本，解决漏洞或重复副本；仅 pnpm 读取，需合并进完整 `package.json` 顶层，勿单独成文件。

12. 小结

标识与发布：name、version、private、files、license 决定 npm 能否发、发什么。
运行与兼容：type、main / exports、engines 影响 Node 与打包器如何解析。
协作安装：dependencies 与 devDependencies 分离；peerDependencies 表达插件与宿主关系。
工程扩展：workspaces、overrides（或 pnpm/yarn 对应字段）服务 monorepo 与依赖钉死。

更细的字段列表与默认值以当前使用的 npm / pnpm / yarn 版本文档为准；锁文件（package-lock.json、pnpm-lock.yaml 等）记录已解析的确切版本，与 package.json 中的范围共同保证可复现安装。

package.json 字段说明：参数字段详解

ON THIS PAGE