[!info] related notes

• 所属 MOC: nodejs-moc
• 相关概念: CommonJS, es6-module-import-export, nodejs-package-managers
• 工具: package-management

package.json

Node.js 项目的”身份证”，描述项目元信息、依赖、脚本和模块系统。

一句话定义

package.json 是 Node.js 项目根目录的配置文件，定义项目名称、版本、依赖、脚本命令和模块行为。

核心字段

{
  "name": "my-app",
  "version": "1.0.0",
  "type": "module",
  "main": "index.js",
  "scripts": {
    "dev": "node app.js",
    "start": "node app.js",
    "test": "node --test"
  },
  "dependencies": {
    "express": "^5.0.0"
  },
  "devDependencies": {
    "eslint": "^9.0.0"
  }
}

关键字段详解

scripts

定义命令别名，通过 npm run <name> 执行。

dependencies vs devDependencies

字段	场景
dependencies	生产环境必需
devDependencies	开发工具（lint、测试、构建）

type

决定 .js 文件按 CommonJS 还是 ESM 解释：

• "commonjs"（默认）：使用 require
• "module"：使用 import

exports vs main

exports 是现代推荐的入口控制方式，比 main 更强大：

{
  "exports": {
    ".": "./dist/index.js",
    "./utils": "./dist/utils.js"
  }
}

版本号规则

格式：主版本.次版本.修订版本

• ^1.2.3：允许次版本和修订版本更新
• ~1.2.3：只允许修订版本更新
• 1.2.3：精确匹配

最容易误解的点

• type: "module" 不是 Node 独有，Vite 等构建工具也依赖它
• exports 优先级高于 main
• dependencies 装多了会增加安装和构建时间
• npm install 默认会装 dependencies 和 devDependencies

放回主题图里看

• CommonJS 模块：CommonJS
• ESM 模块：es6-module-import-export
• 包管理工具：nodejs-package-managers
• Node 运行时总览：javascript-in-nodejs