NPM package.json

上篇教程我们认识了 NPM，知道它是 JavaScript 的包管理器。但 NPM 怎么知道你的项目需要哪些包？版本是多少？入口文件是哪个？

答案就在 package.json 里。

package.json 是什么

package.json 是项目的“身份证”和“说明书”。

它是一个 JSON 格式的文件，放在项目根目录下，记录了项目的所有元信息：

• 项目叫什么名字、版本多少
• 依赖了哪些第三方包
• 有哪些可执行的脚本命令
• 入口文件是哪个

没有 package.json，NPM 就不知道该怎么管理你的项目。

快速生成 package.json

创建一个新项目时，第一步就是生成 package.json。

# 创建项目目录
mkdir my-app
cd my-app

# 交互式生成（会问你一系列问题）
npm init

# 跳过所有问题，直接生成默认配置（推荐新手用这个）
npm init -y

npm init -y 会生成一个最简的 package.json：

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

这个文件你完全可以手动修改，后面会逐一讲解每个字段的用途。

提示：-y 是 --yes 的简写，意思是“全都用默认值”。等以后你熟悉了各字段的含义，也可以用 npm init 交互式填写。

核心字段详解

在实际开发中，最常打交道的就是下面这几个字段。把它们搞懂，就够用了。

name：项目名称

项目的名字，有三个规则：

• 必须是小写字母，不能有大写
• 可以用连字符 - 或下划线 _，但不能以点 . 开头
• 不能有空格

{
  "name": "my-app"        // ✅ 正确
  "name": "my_app"        // ✅ 正确
  "name": "my-app-v2"     // ✅ 正确
  "name": "MyApp"         // ❌ 有大写字母
  "name": "my app"        // ❌ 有空格
}

如果要发布到 npm registry，名字还得是全局唯一的——别人用过的名字你就不能用了。

version：版本号

遵循语义化版本规范：主版本号.次版本号.补丁版本号

{
  "version": "1.0.0"
}

版本号	含义	场景
1.0.0	初始稳定版本	项目首次发布
1.1.0	新增功能（向下兼容）	加了新特性
1.1.1	修复 Bug（向下兼容）	修了个小问题
2.0.0	破坏性变更（不兼容）	重构了 API

关于版本管理，后续会有专门教程详细讲解，这里先有个概念就行。

main：入口文件

当别人 require 或 import 你的项目时，实际加载的就是这个文件。

{
  "main": "index.js"      // 默认值
  "main": "dist/index.js" // 常见于打包后的产物
}

如果项目是纯前端应用（不是发布成包的），这个字段没那么重要。

scripts：脚本命令

这是日常开发中使用最频繁的字段。你可以在 scripts 中定义命令别名，然后通过 npm run 执行。

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview",
    "test": "vitest",
    "lint": "eslint ."
  }
}

执行方式：

npm run dev      # 启动开发服务器
npm run build    # 打包构建
npm run test     # 运行测试

几个实用技巧：

• npm start 和 npm test 可以省略 run：直接 npm start、npm test
• 脚本中可以组合其他脚本："build": "npm run lint && vite build"
• pre 和 post 钩子会自动触发：比如 prebuild 会在 build 之前执行

{
  "scripts": {
    "prebuild": "echo '开始构建...'",
    "build": "vite build",
    "postbuild": "echo '构建完成！'"
  }
}

dependencies：生产依赖

项目运行时必须的依赖包。比如 React、Vue、Express、axios 等。

{
  "dependencies": {
    "react": "^18.2.0",
    "axios": "^1.6.0",
    "express": "^4.18.0"
  }
}

安装时用 npm install <package> 会自动写入这里。

devDependencies：开发依赖

项目开发时需要的工具包，生产环境不需要。比如打包工具、测试框架、代码格式化工具。

{
  "devDependencies": {
    "vite": "^5.0.0",
    "vitest": "^0.34.0",
    "eslint": "^8.0.0",
    "prettier": "^3.0.0"
  }
}

安装时加 -D 或 --save-dev 会写入这里：

npm install -D vitest

如何区分 dependencies 和 devDependencies？

一个简单的判断方法：

问自己：这个包在线上运行时还需要吗？

• 需要 → dependencies
• 不需要 → devDependencies

包	归类	原因
React	dependencies	页面渲染需要它
Vite	devDependencies	只在打包时用，线上不需要
Lodash	dependencies	代码中调用了它的方法
ESLint	devDependencies	只在开发时检查代码规范

其他常用字段

这几个字段用得少一些，但碰到了要知道是什么意思。

private：是否私有

{
  "private": true
}

如果设为 true，NPM 会拒绝发布这个包。对于不想发布到公共仓库的项目，强烈建议加上这个配置，防止手滑把代码发到公网。

description：项目描述

一句话说明这个项目是做什么的，方便别人（或未来的自己）快速了解。

{
  "description": "一个简洁的 Todo 管理应用"
}

keywords：关键词

一组关键词，方便在 npm registry 上被搜索到。发布包时比较有用。

{
  "keywords": ["todo", "react", "typescript"]
}

author：作者

项目作者信息，可以是字符串或对象。

{
  "author": "张三 <zhangsan@example.com>"
}

license：许可证

声明项目的开源许可证类型。

{
  "license": "MIT"  // 最宽松的开源协议
}

一个完整的 package.json

这是一个真实项目（一个 Vite + React + TypeScript 项目）的 package.json：

{
  "name": "todo-app",
  "version": "0.1.0",
  "private": true,
  "description": "一个简洁的 Todo 管理应用",
  "author": "张三",
  "license": "MIT",
  "type": "module",
  "main": "index.js",
  "scripts": {
    "dev": "vite",
    "build": "tsc && vite build",
    "preview": "vite preview",
    "test": "vitest",
    "lint": "eslint . --ext ts,tsx",
    "format": "prettier --write ."
  },
  "dependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0"
  },
  "devDependencies": {
    "@types/react": "^18.2.0",
    "@types/react-dom": "^18.2.0",
    "@vitejs/plugin-react": "^4.0.0",
    "eslint": "^8.0.0",
    "prettier": "^3.0.0",
    "typescript": "^5.0.0",
    "vite": "^5.0.0",
    "vitest": "^0.34.0"
  }
}

常见问题

Q：package.json 需要手动编辑吗？

可以手动改，但大部分情况不需要。npm install 会自动维护 dependencies 和 devDependencies，scripts 一般也是手动添加。手动编辑时注意 JSON 格式要正确（不能有尾随逗号）。

Q：package-lock.json 和 package.json 有什么区别？

简单说：package.json 记录“我要什么包”，package-lock.json 记录“我装了什么版本”。后续教程会详细讲解。

Q：依赖的版本号前面的 ^ 和 ~ 是什么意思？

• ^1.2.3：兼容 1.x.x 的最新版本（不能升到 2.x）
• ~1.2.3：兼容 1.2.x 的最新版本（不能升到 1.3）

后面有专门教程讲版本管理，这里先知道它们控制版本范围就行。

Q：package.json 能写注释吗？

不能。JSON 格式不支持注释。但如果用 JSON5 或特殊工具可以，不过不建议——保持标准 JSON 格式最稳妥。

本篇小结

package.json 是项目的核心配置文件，掌握这几个关键字段就够了：

字段	作用	需要手动改吗
name	项目名称	创建时定好，一般不改
version	版本号	发版时更新
main	入口文件	结构变化时改
scripts	自定义命令	经常改
dependencies	生产依赖	npm install 自动维护
devDependencies	开发依赖	npm install -D 自动维护
private	是否私有	建议设为 true

下篇教程会深入讲解语义化版本，帮你搞懂那些 ^1.2.3 和 ~1.2.3 到底是什么意思，以及如何正确地管理版本号。