package.json初始化与核心字段

package.json是NPM项目的核心配置文件，定义了项目元信息和依赖关系。

package.json初始化

创建package.json

Bash

# 交互式创建，逐步填写信息
npm init

# 快速创建，使用默认值
npm init -y

npm init -y生成的默认文件：

JSON

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

项目名称不能含大写字母和空格，推荐使用kebab-case命名（如my-project）。

name与version字段

name字段

name是包的唯一标识，发布到npmjs.com时必须全局唯一。

JSON

{
  "name": "@myorg/utils"
}

命名规则：

长度不超过214字符
不能以.或_开头
可使用作用域前缀@scope/name

version字段

version遵循语义化版本格式主版本.次版本.补丁版本。

JSON

{
  "version": "1.2.3"
}

位次	含义	示例
主版本	不兼容的API变更	1.x.x → 2.x.x
次版本	向下兼容的功能新增	1.2.x → 1.3.x
补丁版本	向下兼容的问题修复	1.2.3 → 1.2.4

name和version组合构成包的唯一标识，每次发布必须更新version。

dependencies依赖声明

dependencies

运行时必需的依赖，项目上线后仍需要。

Bash

# 安装并写入dependencies
npm install express --save

JSON

{
  "dependencies": {
    "express": "^4.18.2"
  }
}

devDependencies

开发阶段使用的依赖，如测试框架、构建工具，不会被打入生产包。

Bash

# 安装并写入devDependencies
npm install jest --save-dev

JSON

{
  "devDependencies": {
    "jest": "^29.7.0"
  }
}

npm install --production或设置NODE_ENV=production时不会安装devDependencies。

要点总结

npm init -y可快速生成package.json，再按需修改
name必须全局唯一，version遵循SemVer格式，两者组合唯一标识一个包
dependencies放运行时依赖，devDependencies放开发时依赖
生产环境安装可通过--production跳过devDependencies