1. package.json 的工程化价值当你接手一个 Node.js 项目时第一个打开的文件大概率是 package.json。这个看似简单的 JSON 文件实际上是整个项目的控制中枢。我见过不少开发者只把它当作依赖清单这就像把智能手机当闹钟用——实在是大材小用了。现代 Node.js 项目中package.json 至少承担着三大核心职责项目身份证包含名称、版本、许可证等元数据依赖管理器记录生产环境与开发环境所需的所有模块工程化枢纽通过 scripts 字段实现自动化工作流举个真实案例去年我们团队接手了一个遗留项目其 package.json 里只有基本的依赖信息。通过重构 scripts 配置我们将构建时间从 3 分钟缩短到 45 秒。这就是工程化配置的威力。2. 依赖管理的进阶技巧2.1 版本控制的艺术你可能见过这样的版本号dependencies: { lodash: ^4.17.21, express: ~4.18.2 }这里的^和~可不是随便画的符号^4.17.21表示允许自动升级到 4.x.x 的最新版但不会升级到 5.0.0~4.18.2则只允许升级到 4.18.x 的最新补丁版本在实际项目中我推荐使用npm config set save-prefix~将默认符号设为~这能更好地控制依赖升级风险。曾经有个项目因为^导致依赖自动升级到不兼容版本线上服务直接崩溃。2.2 依赖分类管理成熟的工程化项目会严格区分三种依赖依赖类型安装参数使用场景打包时包含dependencies--save生产环境必需是devDependencies--save-dev开发测试用否peerDependencies--peer插件类库否特别要注意 peerDependencies。比如开发 React 组件库时peerDependencies: { react: 16.8.0 }这表示你的库需要宿主环境提供 React但不会自己安装 React。3. 条件导出与模块封装3.1 exports 字段的妙用现代 Node.js 支持通过 exports 字段实现条件导出exports: { .: { import: ./dist/esm/index.js, require: ./dist/cjs/index.js, default: ./dist/umd/index.js }, ./utils: ./src/utils/index.js }这种配置可以实现根据使用环境自动切换 ESM/CJS 模块隐藏内部模块路径用户无法 require(你的库/src/internal)按需加载不同环境下的实现我在开发跨端 SDK 时就深有体会通过 exports 配置同一份代码可以自动适配 Node.js 和浏览器环境。3.2 发布控制 files 字段总有些文件不该发布到 npmfiles: [ dist, types, README.md ]这个配置就像.gitignore 的反向操作只允许特定文件被发布。有次我忘记配置这个字段结果把测试用例和本地配置文件都发布到了 npm实在太尴尬了。4. 自动化脚本工程化4.1 生命周期钩子package.json 的 scripts 不只是简单的命令别名scripts: { prebuild: rimraf dist, build: tsc, postbuild: size-limit }这些以 pre/post 开头的脚本会自动在对应阶段执行。我常用 precommit 钩子来运行代码检查husky: { hooks: { pre-commit: lint-staged } }4.2 复杂脚本的优化当脚本变得复杂时可以考虑将长命令拆分成单独的脚本文件使用工具库如 zx 编写更强大的脚本通过 npm-run-all 实现并行/串行执行比如这样优化构建流程scripts: { build: run-s clean compile bundle, clean: rimraf dist, compile: tsc, bundle: rollup -c }5. 环境限定与工程约束5.1 环境检测配置通过以下字段可以确保项目运行在正确的环境engines: { node: 16.0.0, npm: 8.0.0 }, os: [darwin, linux], cpu: [x64, arm64]我在 CI 环境中会加上这样的检查npm config set engine-strict true5.2 工作区管理monorepo 项目一定要用 workspacesworkspaces: [ packages/*, examples/* ]这比传统的 lerna 配置更简洁而且原生支持依赖提升hoisting跨包链接symlink统一安装命令最近将一个大型项目改造成 workspaces 后安装时间从 15 分钟降到了 2 分钟。
Node.js 第三章：package.json 的进阶配置与工程化实践
1. package.json 的工程化价值当你接手一个 Node.js 项目时第一个打开的文件大概率是 package.json。这个看似简单的 JSON 文件实际上是整个项目的控制中枢。我见过不少开发者只把它当作依赖清单这就像把智能手机当闹钟用——实在是大材小用了。现代 Node.js 项目中package.json 至少承担着三大核心职责项目身份证包含名称、版本、许可证等元数据依赖管理器记录生产环境与开发环境所需的所有模块工程化枢纽通过 scripts 字段实现自动化工作流举个真实案例去年我们团队接手了一个遗留项目其 package.json 里只有基本的依赖信息。通过重构 scripts 配置我们将构建时间从 3 分钟缩短到 45 秒。这就是工程化配置的威力。2. 依赖管理的进阶技巧2.1 版本控制的艺术你可能见过这样的版本号dependencies: { lodash: ^4.17.21, express: ~4.18.2 }这里的^和~可不是随便画的符号^4.17.21表示允许自动升级到 4.x.x 的最新版但不会升级到 5.0.0~4.18.2则只允许升级到 4.18.x 的最新补丁版本在实际项目中我推荐使用npm config set save-prefix~将默认符号设为~这能更好地控制依赖升级风险。曾经有个项目因为^导致依赖自动升级到不兼容版本线上服务直接崩溃。2.2 依赖分类管理成熟的工程化项目会严格区分三种依赖依赖类型安装参数使用场景打包时包含dependencies--save生产环境必需是devDependencies--save-dev开发测试用否peerDependencies--peer插件类库否特别要注意 peerDependencies。比如开发 React 组件库时peerDependencies: { react: 16.8.0 }这表示你的库需要宿主环境提供 React但不会自己安装 React。3. 条件导出与模块封装3.1 exports 字段的妙用现代 Node.js 支持通过 exports 字段实现条件导出exports: { .: { import: ./dist/esm/index.js, require: ./dist/cjs/index.js, default: ./dist/umd/index.js }, ./utils: ./src/utils/index.js }这种配置可以实现根据使用环境自动切换 ESM/CJS 模块隐藏内部模块路径用户无法 require(你的库/src/internal)按需加载不同环境下的实现我在开发跨端 SDK 时就深有体会通过 exports 配置同一份代码可以自动适配 Node.js 和浏览器环境。3.2 发布控制 files 字段总有些文件不该发布到 npmfiles: [ dist, types, README.md ]这个配置就像.gitignore 的反向操作只允许特定文件被发布。有次我忘记配置这个字段结果把测试用例和本地配置文件都发布到了 npm实在太尴尬了。4. 自动化脚本工程化4.1 生命周期钩子package.json 的 scripts 不只是简单的命令别名scripts: { prebuild: rimraf dist, build: tsc, postbuild: size-limit }这些以 pre/post 开头的脚本会自动在对应阶段执行。我常用 precommit 钩子来运行代码检查husky: { hooks: { pre-commit: lint-staged } }4.2 复杂脚本的优化当脚本变得复杂时可以考虑将长命令拆分成单独的脚本文件使用工具库如 zx 编写更强大的脚本通过 npm-run-all 实现并行/串行执行比如这样优化构建流程scripts: { build: run-s clean compile bundle, clean: rimraf dist, compile: tsc, bundle: rollup -c }5. 环境限定与工程约束5.1 环境检测配置通过以下字段可以确保项目运行在正确的环境engines: { node: 16.0.0, npm: 8.0.0 }, os: [darwin, linux], cpu: [x64, arm64]我在 CI 环境中会加上这样的检查npm config set engine-strict true5.2 工作区管理monorepo 项目一定要用 workspacesworkspaces: [ packages/*, examples/* ]这比传统的 lerna 配置更简洁而且原生支持依赖提升hoisting跨包链接symlink统一安装命令最近将一个大型项目改造成 workspaces 后安装时间从 15 分钟降到了 2 分钟。
