package.json文件详解

package.json 是 Node.js 项目的核心配置文件，定义了项目的元信息、依赖关系、脚本命令等。它采用 JSON 格式，通常位于项目根目录，是 npm 或 yarn 等包管理工具操作的基础。

package.json 的基本结构

一个典型的 package.json 文件包含以下主要字段：

{
  "name": "my-project",
  "version": "1.0.0",
  "description": "A sample Node.js project",
  "main": "index.js",
  "scripts": {
    "start": "node index.js"
  },
  "dependencies": {
    "express": "^4.17.1"
  },
  "devDependencies": {
    "eslint": "^7.32.0"
  }
}

核心字段详解

name 和 version

name 和 version 是必填字段，它们共同构成项目的唯一标识符。

• name 规则：
  • 长度 ≤ 214 字符
  • 不能以点或下划线开头
  • 不能包含大写字母
  • 不能与官方包重名

{
  "name": "my-awesome-project",
  "version": "1.0.0-alpha.1"
}

版本号遵循语义化版本规范（SemVer）：

• MAJOR.MINOR.PATCH（主版本.次版本.修订号）
• 预发布版本可添加后缀，如 -alpha、-beta

description 和 keywords

这两个字段用于包的可发现性：

{
  "description": "A lightweight utility library for data validation",
  "keywords": ["validation", "utility", "javascript"]
}

main 和 module

定义包的入口文件：

{
  "main": "lib/index.js",        // CommonJS 入口
  "module": "esm/index.js"       // ES Module 入口
}

scripts

定义可运行的 npm 脚本：

{
  "scripts": {
    "start": "node server.js",
    "test": "jest",
    "build": "webpack --mode production",
    "lint": "eslint .",
    "prepublishOnly": "npm test && npm run build"
  }
}

常用脚本钩子：

• pre/post 前缀可创建前置/后置脚本
• prepublish、prepare、prepublishOnly 等生命周期钩子

依赖管理

dependencies 和 devDependencies

{
  "dependencies": {
    "react": "^17.0.2",
    "lodash": "~4.17.21"
  },
  "devDependencies": {
    "webpack": "^5.0.0",
    "@types/node": "14.14.37"
  }
}

版本号前缀含义：

• ^：允许次版本和修订号更新
• ~：只允许修订号更新
• 无前缀：精确版本

peerDependencies

声明宿主环境必须提供的依赖：

{
  "peerDependencies": {
    "react": ">=16.8.0"
  }
}

bundledDependencies

指定需要打包进发布包的依赖：

{
  "bundledDependencies": ["package-a", "package-b"]
}

配置进阶

engines

指定运行环境要求：

{
  "engines": {
    "node": ">=12.0.0",
    "npm": ">=6.0.0"
  }
}

os 和 cpu

限制运行平台：

{
  "os": ["darwin", "linux"],
  "cpu": ["x64", "arm64"]
}

files

控制发布包含的文件：

{
  "files": [
    "dist/",
    "lib/",
    "README.md"
  ]
}

repository

指定代码仓库信息：

{
  "repository": {
    "type": "git",
    "url": "https://github.com/user/repo.git"
  }
}

私有包配置

private

防止意外发布：

{
  "private": true
}

publishConfig

自定义发布配置：

{
  "publishConfig": {
    "registry": "https://registry.npmjs.org/",
    "access": "public"
  }
}

工作区配置

workspaces

Monorepo 项目配置：

{
  "workspaces": [
    "packages/*",
    "shared/*"
  ]
}

自定义字段

可以添加项目特定配置：

{
  "config": {
    "port": 8080
  },
  "myCustomConfig": {
    "featureFlags": {
      "newUI": true
    }
  }
}

完整示例

综合示例：

{
  "name": "full-featured-project",
  "version": "1.2.3",
  "description": "A comprehensive example package.json",
  "main": "dist/index.js",
  "module": "dist/index.esm.js",
  "types": "dist/index.d.ts",
  "files": ["dist"],
  "scripts": {
    "build": "rollup -c",
    "test": "jest",
    "lint": "eslint src",
    "prepublishOnly": "npm run build && npm test"
  },
  "dependencies": {
    "axios": "^0.21.1"
  },
  "devDependencies": {
    "@types/jest": "^26.0.20",
    "jest": "^26.6.3"
  },
  "peerDependencies": {
    "react": ">=16.8.0"
  },
  "engines": {
    "node": ">=12.0.0"
  },
  "repository": {
    "type": "git",
    "url": "https://github.com/user/repo.git"
  },
  "keywords": ["example", "demo"],
  "license": "MIT",
  "bugs": {
    "url": "https://github.com/user/repo/issues"
  },
  "homepage": "https://github.com/user/repo#readme",
  "config": {
    "port": 3000
  }
}