深入理解 package.json：前端项目的 "身份证"

前言

每一个 Node.js 项目都绕不开一个文件——package.json。
它像项目的“身份证”，又像“瑞士军刀”：

• 告诉 npm 你是谁（name、version、license）
• 告诉打包器 怎么引入你（main、module、exports）
• 告诉 CI 怎么测试你（scripts.test）
• 告诉用户 怎么使用你（bin、scripts、dependencies）

本文用“渐进式”结构，带你从最小可运行一路到企业级开源库所需的全部字段与技巧。读完可以：

1. 手写零报错 package.json
2. 正确拆分 dependencies 与 peerDependencies
3. 让 webpack/vite/Node 同时识别你的库
4. 避免 90% 的“为什么本地能跑，一发包就崩”

1. 最小可运行版本（MVP）

新建文件夹，执行 npm init -y，得到：

{
  "name": "demo",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo "Error: no test specified" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

即可：

• node index.js 运行
• npm test 触发脚本

但离“能用”还差 3 件事：

1. 把 license 换成 SPDX 标准标识（MIT / Apache-2.0）
2. 加 "private": true，防止误发 npm
3. 删除无用字段，保留核心 6 项：

{
  "name": "demo",
  "version": "1.0.0",
  "main": "index.js",
  "private": true,
  "scripts": {
    "start": "node index.js"
  },
  "license": "MIT"
}

2. 依赖管理三板斧

口诀：

踩坑：

• peerDependencies 版本范围过严会导致用户无法安装！
  正确：">=16.8.0"
  错误："16.8.0"（只允许 exact 版本）

3. 脚本进阶：一条命令跑完开发全流程

"scripts": {
  "dev": "vite",
  "build": "tsc && vite build",
  "test": "vitest",
  "lint": "eslint . --ext .ts,.tsx",
  "lint:fix": "eslint . --ext .ts,.tsx --fix",
  "prepare": "husky install",
  "prepublishOnly": "npm run build && npm test"
}

生命周期图解：

npm install → 触发 prepare → 自动装 husky 钩子  
npm publish → 触发 prepublishOnly → 保证发布的是 dist 产物

跨平台兼容：

"build": "cross-env NODE_ENV=production tsc && vite build"

4. 让三方库正确引入你：main vs module vs exports

现代库模板：

{
  "type": "module",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs"
    },
    "./utils": {
      "types": "./dist/utils.d.ts",
      "import": "./dist/utils.mjs",
      "require": "./dist/utils.cjs"
    }
  }
}

收益：

• import {} from 'your-lib/utils' 直接子路径
• 用户 CommonJS / ESM 均可使用
• TypeScript 提示不丢失

5. 发布配置：让包体积瘦身 70%

{
  "files": ["dist", "README.md", "LICENSE"],
  "sideEffects": false,
  "publishConfig": {
    "registry": "https://registry.npmjs.org",
    "access": "public"
  }
}

• files 白名单：防止把源码、测试、脚本发到 npm
• sideEffects: false 告诉 webpack 可以摇树优化
• 公司内网发布：registry 指向私有 Verdaccio / Nexus

6. 企业级开源库 checklist

示例 CI 片段（.github/workflows/publish.yml）：

- name: Publish
  if: github.ref == 'refs/heads/main'
  run: |
    npm config set //registry.npmjs.org/:_authToken=${{ secrets.NPM_TOKEN }}
    npm publish

7. 可视化总结：一张思维导图

（文字版）

package.json
├─ 元信息（name、version、license、private）
├─ 依赖（dependencies / dev / peer / optional）
├─ 脚本（scripts + 生命周期）
├─ 入口（main → module → exports 渐进）
├─ 发布（files、sideEffects、publishConfig）
└─ 约束（engines、os、cpu）

8. 常见报错速查表

9. 结语

package.json 很小，却贯穿了 Node.js 项目的全生命周期：
开发 → 测试 → 构建 → 发布 → 依赖治理。
掌握它，你就拥有了：

• 更小的包体积
• 更快的安装速度
• 更少的“在我电脑能跑”事故

把本文 checklist 保存为备忘录，下次新建项目直接套用，即可一步到位。
Happy coding!

10. 附录：模板仓库

GitHub 搜 npm-lib-boilerplate-2025，已集成：

• TypeScript + Vite + Vitest
• GitHub Actions 自动发布
• husky + lint-staged 代码检查
• 示例 package.json 与本文明细 100% 对应

克隆即可开始你的下一个开源库。