package.json

Node.js 项目的元数据与配置文件，JSON 格式。定义包名、版本、依赖、脚本入口等信息，是 npm/yarn/pnpm/bun 等包管理器和大多数构建工具的统一配置载体。

核心字段

字段	说明
`name`	包名，发布到 npm registry 时的唯一标识，支持 `@scope/name` 形式的 scoped package
`version`	版本号，遵循 semver
`private`	设为 `true` 时禁止被 `npm publish` 发布，常用于应用（非库）项目
`main` / `module` / `exports`	包的入口文件；`exports` 是现代写法，支持按条件（如 ESM/CJS）分流入口
`scripts`	命令别名表，`npm run <name>` / `yarn <name>` / `bun run <name>` 触发
`dependencies`	运行时依赖
`devDependencies`	仅开发/构建阶段需要的依赖
`peerDependencies`	期望由使用者环境提供的依赖（常见于插件、UI 组件库）
`engines`	声明所需的 Node/包管理器版本范围
`type`	`"module"` 表示 `.js` 按 ESM 解析，默认（或 `"commonjs"`）按 CJS 解析

scripts 字段：约定与常见模式

scripts 是最常被自定义的部分，本质是给 shell 命令起别名，可以互相组合、注入环境变量、并行执行。常见约定：

dev：本地开发启动命令，通常带热重载/watch
build：生产构建
start：生产环境启动（构建产物运行），或作为 dev 的同义词，视项目而定
test：测试入口，npm test 会默认查找这个脚本

组合技巧：

{
  "scripts": {
    // 用 && 顺序执行多个命令
    "start": "vite build && electrobun dev",
 
    // 用 concurrently 并行跑多个进程（各自独立生命周期）
    "dev:hmr": "concurrently \"bun run hmr\" \"bun run start\"",
 
    // 命令前置环境变量，支持 ${VAR:-default} 语法做默认值兜底
    "dev:cef": "LLM_SPACE_DESKTOP_RENDERER=cef LLM_SPACE_DESKTOP_CDP_PORT=${LLM_SPACE_DESKTOP_CDP_PORT:-9333} bun run dev:hmr",
 
    // 按渠道/环境区分构建变体
    "build:canary": "vite build && electrobun build --env=canary"
  }
}

HMR: Hot Module Replacement（热模块替换），运行时只替换变动的模块，不刷新整页，保留应用状态。Vite/webpack/Parcel 等构建工具都内置支持。上面这组脚本来自一个 Electrobun（基于 Bun 的轻量桌面应用框架）桌面项目：dev 走无 HMR 的构建后启动，dev:hmr 用 concurrently 同时跑 Vite dev server 和桌面壳启动，dev:cef 在此基础上切换渲染引擎为 CEF 并开放调试端口，build:canary 走独立的灰度发布通道打包。这种”基础命令 + 变体命令用冒号分层命名”是 Node 生态里非常常见的组织方式。

与包管理器/运行时的关系

npm/yarn/pnpm：都直接读 dependencies/scripts 等标准字段，行为基本一致，差异主要在依赖解析算法（扁平 vs 严格隔离）和 lockfile 格式
bun：既是包管理器也是运行时，bun run <script> 执行 scripts 里的命令；bun run <file>.ts 可以直接执行 TS/JS 文件，无需预编译，但这也是 bun run dev 类命令启动偏慢的原因之一——每次都要动态解析、转译再执行
workspaces 字段：在 monorepo 根 package.json 声明 "workspaces": ["packages/*"]，npm/yarn/pnpm/bun 均支持，用于统一管理多个子包的依赖安装与链接

zhaoweiguo 的知识库

目录

package.json

核心字段

scripts 字段：约定与常见模式

与包管理器/运行时的关系

相关

关系图谱

目录

反向链接