1. 为什么 package.json 值得你花时间吃透如果你写 JavaScript 或者 TypeScript哪怕只是偶尔碰一下前端项目package.json这个文件你肯定见过。它躺在项目根目录里看起来就是一堆 JSON 键值对很多人平时只关心两件事dependencies里装了什么包scripts里怎么启动项目。剩下的字段要么视而不见要么复制粘贴的时候顺手带过来从来没想过它们是干什么用的。我刚开始做项目那几年也是这个状态。直到有一次排查一个线上问题发现构建产物里混进了开发环境的调试代码查了半天才定位到是dependencies和devDependencies放错了位置还有一次发布一个工具库别人装完之后类型提示全丢了最后发现是types字段没配对。这些坑踩多了之后我才意识到package.json根本不是一个“配置文件”那么简单它是整个 Node 生态里包与包之间沟通的契约是 npm 理解你项目的唯一入口。这篇文章就是把我这些年跟package.json打交道积累下来的东西系统梳理一遍。从最基础的字段含义到依赖版本号的语义化规则再到exports、workspaces这些相对新但越来越重要的能力我都会结合真实项目里的使用场景讲清楚。不管你是刚入行的新手还是已经写了几年业务代码想往工程化方向走的人看完之后应该都能对这个文件有一个更完整的认知至少下次再看到不认识的字段你知道该去哪里查、它大概会影响什么。文章里涉及的所有项目名、包名、人名我都会用虚构代称但字段名、版本规则、行为逻辑都是真实可验证的。你可以边看边打开自己手头的项目对照着检查效果会更好。2. package.json 的整体结构与核心定位2.1 它在 Node 生态里到底扮演什么角色要理解package.json得先搞清楚 npm 是怎么看待一个项目的。在 npm 的世界里任何一个包含package.json的目录都可以被当作一个“包”来处理。这个文件承担了三个层面的职责身份标识、依赖声明、行为定义。身份标识指的是name和version这两个字段它们组合起来构成了这个包在 registry 里的唯一坐标。依赖声明就是dependencies、devDependencies、peerDependencies这些字段告诉 npm 装这个包的时候还需要哪些东西。行为定义则包括scripts、main、exports、bin等决定了这个包被安装后怎么被调用、入口在哪里、有哪些命令可以执行。很多人会把package.json和package-lock.json搞混。简单说前者是你手写的“意图声明”后者是 npm 根据你的声明实际解析出来的“精确快照”。你写lodash: ^4.17.0这是意图lock 文件里记录的4.17.21加上 integrity 哈希这是实际结果。两者配合才能保证团队里每个人装出来的依赖树是一致的。2.2 一个最小可用文件长什么样理论上一个合法的package.json只需要name和version两个字段就能通过校验。但实际项目里当然不会这么寒酸。下面是一个我常用的起步模板你可以直接拿去改{ name: my-project, version: 1.0.0, description: 一个用于演示的项目, main: dist/index.js, types: dist/index.d.ts, scripts: { build: tsc, test: jest }, keywords: [demo, template], author: someone, license: MIT }这个模板里每个字段都有明确用途后面我会逐个展开。这里先提醒一点name字段有命名规范不能有大写字母、空格也不能以点或下划线开头长度不能超过 214 个字符。如果你打算发布到公共 registry还要注意名字不能被别人占用。2.3 字段的分类逻辑我把package.json里的字段大致分成四类这样记忆和理解都会清晰很多分类代表字段作用元信息name, version, description, author, license描述这个包是谁、干什么用的入口与导出main, module, types, exports, browser告诉外部怎么引用这个包依赖管理dependencies, devDependencies, peerDependencies, optionalDependencies声明运行和开发所需的其他包脚本与工具scripts, bin, engines, config定义可执行命令和运行环境要求这个分类不是官方标准但用起来很顺手。你在排查问题时先判断问题属于哪一类然后去对应字段里找原因效率会高很多。3. 依赖管理字段的深度拆解3.1 dependencies 与 devDependencies 的边界怎么划这是最常被问、也最容易出错的一组字段。核心原则只有一句话运行时需要的放 dependencies只在开发、构建、测试阶段需要的放 devDependencies。什么叫“运行时需要”就是这个包被安装到别人项目里之后如果缺少这个依赖代码就会报错或者功能不正常。比如你写了一个 React 组件库那react就是运行时依赖必须放dependencies。但如果你只是用typescript来编译代码编译完的产物里并不包含 tsc 本身那typescript就应该放devDependencies。我见过最常见的错误是把构建工具、测试框架、类型定义全都塞进dependencies。这样做本身不会让代码跑不起来但会带来两个后果一是别人安装你的包时会莫名其妙多下载一堆根本用不到的东西安装体积和耗时都会增加二是在一些对依赖体积敏感的场景比如前端打包可能会把不该打进去的东西打进去。有一个判断技巧很实用问自己“如果把这个包删掉用户在使用我的包的功能时会不会出问题”会就是dependencies不会就是devDependencies。3.2 peerDependencies 的真实用途peerDependencies是很多人一直没搞明白的字段。它的含义是“我用到了某个包但我不自己安装它而是要求使用我的人来提供。”最典型的场景就是插件体系。假设你写了一个 Webpack 插件这个插件必须配合 Webpack 使用但你不应该把 Webpack 打包进插件里因为使用者自己的项目里已经有 Webpack 了。这时候你就把 Webpack 声明在peerDependencies里。从 npm 7 开始peerDependencies的默认行为发生了变化如果使用者没有安装对应的 peer 依赖npm 会尝试自动安装。这个变化解决了很多“装完插件发现缺依赖”的问题但也带来了一些意料之外的版本冲突。所以在声明 peer 依赖时版本范围要尽量写得宽松一些比如4.0.0而不是^4.17.0给使用者留出选择空间。3.3 optionalDependencies 与 bundledDependenciesoptionalDependencies的语义是“装不上也没关系”。npm 在安装时会尝试安装这些依赖但如果失败比如某个平台没有对应的二进制包不会导致整个安装过程失败。这个字段用得不多主要出现在一些需要跨平台兼容的底层工具里。bundledDependencies也可以写成bundleDependencies则是把依赖直接打包进你的发布产物里。这个字段现在很少用了因为现代 npm 的依赖解析已经很可靠但在一些离线部署或者需要锁定特定版本的场景下仍然有用。3.4 版本号语义化规则与选择策略版本号是依赖管理里最容易埋雷的地方。npm 遵循的是语义化版本SemVer规范格式是主版本号.次版本号.修订号。规则很简单主版本号变化有不兼容的 API 修改次版本号变化新增了向后兼容的功能修订号变化修复了向后兼容的 bug在package.json里写版本范围时常用的前缀有这几种写法含义示例匹配^1.2.3允许次版本和修订号升级1.2.3 到 1.x.x~1.2.3只允许修订号升级1.2.3 到 1.2.x1.2.3精确锁定只有 1.2.31.2.3大于等于1.2.3 及以上*任意版本任何版本我的经验是应用项目用^工具库用~或精确版本。应用项目不怕自动升级因为你有 lock 文件和测试兜底但工具库如果依赖范围太宽使用者装到的版本可能跟你测试时不一样容易出兼容性问题。注意不要手动去改package-lock.json里的版本号那个文件应该由 npm 自动维护。你只需要改package.json然后重新执行安装命令。4. 入口与导出字段的实战解析4.1 main、module、browser 的分工这三个字段都跟“入口”有关但面向的环境不同。main是最传统的字段指向 CommonJS 格式的入口文件。Node.js 环境默认读这个字段。module是社区约定指向 ES Module 格式的入口打包工具如 Rollup、Webpack会优先读它以便做 tree-shaking。browser则用于指定浏览器环境下的替代入口可以是一个字符串也可以是一个对象映射把某些 Node 专用的模块替换成浏览器可用的版本。一个典型的双格式包会这样写{ main: dist/index.cjs.js, module: dist/index.esm.js, browser: dist/index.umd.js }这样 Node 环境用 CJS打包工具用 ESM直接在浏览器里用 script 标签引入时用 UMD。4.2 types 与类型声明的正确姿势如果你用 TypeScript 写库types字段必须指向生成的.d.ts文件。很多人会把它写成源码里的.ts文件路径这是不对的——使用者装的是你发布后的产物源码文件通常不在发布范围内。正确的做法是在tsconfig.json里开启declaration: true让编译器生成类型声明文件然后让types指向输出目录里的对应文件。如果你同时提供了 CJS 和 ESM 两套产物最好用exports字段里的types条件分别指定避免类型解析出错。4.3 exports 字段新一代的入口控制exports是 Node.js 12.7 之后引入的字段它比main更强大也更严格。一旦你定义了exportsNode 就会忽略main所有外部引用都必须通过exports里声明的路径来访问。它的基本结构是这样的{ exports: { .: { types: ./dist/index.d.ts, import: ./dist/index.esm.js, require: ./dist/index.cjs.js }, ./utils: { import: ./dist/utils.esm.js, require: ./dist/utils.cjs.js } } }这个配置做了两件事一是定义了根入口在不同模块系统下的解析路径二是暴露了一个子路径./utils让使用者可以按需引入。exports的一个重要作用是封装内部结构。在没有exports的年代使用者可以引用你包里的任意文件比如require(your-pkg/dist/internal/helper)。这很危险因为内部文件随时可能重构。有了exports之后只有你显式暴露的路径才能被访问其他路径一律报错。这对库作者来说是一个很好的保护机制。提示exports的路径必须以./开头不能写成dist/index.js。这个细节很容易忽略但写错了会直接导致解析失败。5. 脚本、二进制与运行环境配置5.1 scripts 的进阶用法scripts字段大家都会用但有些技巧能让它更好用。首先是pre和post钩子如果你定义了build脚本那么prebuild会在它之前执行postbuild会在它之后执行。这个机制可以用来做清理、校验、通知等事情。其次是跨平台兼容。scripts里的命令默认由系统的 shell 执行这意味着 Windows 和 Unix 下的写法可能不一样。比如rm -rf dist在 Windows 的 cmd 里就不管用。解决办法是用rimraf这类跨平台工具或者用 Node 脚本代替 shell 命令。还有一个实用技巧是用npm-run-all或者concurrently来并行或串行执行多个脚本。比如{ scripts: { build: npm-run-all clean build:*, build:js: tsc, build:css: sass src:dist, clean: rimraf dist } }这样build会先执行clean然后依次执行build:js和build:css逻辑清晰也方便单独调用某个子任务。5.2 bin 字段与命令行工具如果你想让自己的包提供一个命令行命令就需要用到bin字段。最简单的写法是{ bin: { my-cli: ./bin/cli.js } }这样使用者全局安装或者通过npx调用时就可以直接执行my-cli。对应的cli.js文件开头必须加上 shebang#!/usr/bin/env node没有这行系统不知道用什么解释器来执行这个文件。另外bin指向的文件在发布时必须有可执行权限npm 在打包时会自动处理但如果你手动拷贝文件就要注意这一点。5.3 engines 与 packageManagerengines字段用来声明你的包对 Node.js 或 npm 版本的要求{ engines: { node: 16.0.0, npm: 8.0.0 } }默认情况下npm 只会在版本不满足时给出警告不会阻止安装。如果你希望强制阻止可以在项目里加一个.npmrc文件写入engine-stricttrue。packageManager字段是较新的约定用来指定项目应该使用哪个包管理器及其版本比如packageManager: pnpm8.6.0。配合 Corepack 使用可以确保团队成员用同一套工具链减少“我这里能跑你那里跑不了”的问题。6. 常见问题排查与避坑经验6.1 依赖装不上或版本冲突怎么办这是最高频的问题。排查思路我一般按这个顺序走第一步删掉node_modules和package-lock.json重新安装。很多问题是缓存或者 lock 文件损坏导致的重装能解决一大半。第二步如果重装无效用npm ls 包名查看这个包被谁依赖了、装了几个版本。版本冲突往往是因为不同的包依赖了同一个包的不兼容版本。第三步如果确实存在无法调和的冲突可以考虑用overrides字段npm 8.3强制指定某个包的版本{ overrides: { some-package: 2.0.0 } }这个能力要谨慎使用因为它可能让某个依赖拿到它并不兼容的版本。用之前最好确认一下被覆盖的包在目标版本下是否还能正常工作。6.2 发布后类型提示丢失这个问题通常有三个原因types字段路径写错、.d.ts文件没有被包含在发布产物里、或者exports里没有声明types条件。排查时可以先执行npm pack生成一个 tarball解压看看里面到底有哪些文件。如果.d.ts不在里面就要检查files字段或者.npmignore是不是把它排除了。6.3 files 字段与发布范围控制files字段决定了哪些文件会被发布到 registry。不写这个字段的话npm 会发布除了.npmignore和默认忽略列表之外的所有文件很容易把测试代码、配置文件、甚至密钥文件发出去。我的习惯是显式声明files{ files: [dist, README.md, LICENSE] }这样只有dist目录和两个说明文件会被发布干净利落。发布前用npm pack --dry-run预览一下文件列表确认没问题再正式发。6.4 常见问题速查表现象可能原因解决方向安装时报 peer 依赖缺失peerDependencies 未满足手动安装对应 peer 包或调整版本打包体积异常大开发依赖放进了 dependencies检查依赖分类移到 devDependencies引用子路径报错exports 未暴露该路径在 exports 中添加对应子路径类型提示不生效types 路径错误或文件未发布检查 types 字段和 files 字段命令执行报权限错误bin 文件缺少 shebang 或权限添加 shebang检查文件权限不同环境装出不同版本缺少 lock 文件或版本范围过宽提交 lock 文件收紧版本范围7. 进阶字段与工程化实践7.1 workspaces 与 monorepoworkspaces字段让一个仓库可以管理多个包是 monorepo 的基础。基本写法是{ workspaces: [packages/*] }这样packages目录下的每个子目录都会被当作一个独立的包来处理npm 会把它们之间的依赖关系自动链接起来不需要手动npm link。对于维护多个相互依赖的包的项目来说这个能力能省掉大量繁琐的操作。使用 workspaces 时要注意一点根目录的package.json通常设为private: true避免误发布。各个子包的依赖尽量声明在子包自己的package.json里而不是全部堆在根目录否则依赖关系会变得难以追踪。7.2 private 字段与防误发布private: true是一个简单但极其重要的字段。加上它之后npm 会拒绝发布这个包。对于公司内部项目、示例项目、根目录的 monorepo 配置来说这个字段应该默认加上。我见过不止一次有人不小心把内部项目发到了公共 registry虽然可以撤回但处理起来很麻烦。7.3 条件导出与多环境适配exports字段支持条件导出可以根据不同的环境返回不同的文件。除了前面提到的import、require、types还有node、browser、default等条件。一个完整的例子{ exports: { .: { types: ./dist/index.d.ts, browser: ./dist/index.browser.js, node: { import: ./dist/index.node.esm.js, require: ./dist/index.node.cjs.js }, default: ./dist/index.esm.js } } }条件的匹配是从上到下依次判断的所以顺序很重要。types必须放在最前面default放在最后作为兜底。7.4 版本发布与 changelog 维护版本号不是随便定的。每次发布前想清楚这次改动属于哪一类修 bug 就升修订号加功能就升次版本号有破坏性变更就升主版本号。配合CHANGELOG.md记录每个版本的变化对使用你包的人来说是很大的帮助。如果团队规模不大手动维护 changelog 完全够用。如果发布频繁可以考虑用changesets或者standard-version这类工具来自动化版本管理和 changelog 生成。工具的选择取决于团队习惯没有绝对的好坏。8. 我个人的一些使用习惯写了这么多年package.json有几个习惯我觉得挺有价值分享出来供参考。第一每次新增依赖都问一句“这是运行时还是开发时”。这个动作只需要几秒钟但能避免后面大量的依赖分类混乱。第二发布前一定跑npm pack --dry-run。这个命令会列出即将发布的文件清单比任何检查都直观。我靠它拦下过好几次误包含的测试文件和本地配置。第三版本范围宁紧勿松。尤其是工具库依赖范围写宽了使用者装到的版本可能跟你测试的完全不一样。宁可让使用者偶尔遇到版本冲突手动解决也不要让他们在不知情的情况下装到一个你没验证过的版本。第四把package.json当成代码来维护。它值得被 review值得有注释虽然 JSON 不支持注释但可以在 README 里说明值得在重构时一起整理。一个混乱的package.json往往是项目工程化水平的一个缩影。这些经验没有什么高深的理论都是在一次次踩坑和修坑中攒下来的。你如果刚开始接触这些字段不用一次性全部记住先把dependencies、scripts、main、types这几个最常用的搞清楚其他的遇到再查、再用、再记慢慢就熟了。