package.json配置详解package.json 详细配置解析 package.json 是 Node.js 项

`package.json` 详细配置解析

package.json 是 Node.js 项目和前端项目的核心配置文件，它定义了项目的元数据、依赖项、脚本命令等重要信息。以下是全面的配置解析：

基础字段

1. 必填字段

{
  "name": "my-project",       // 项目名称（全小写，可包含连字符）
  "version": "1.0.0"         // 版本号（遵循语义化版本 semver）
}

依赖管理

2. 依赖配置

{
  "dependencies": {          // 生产依赖
    "react": "^18.2.0",
    "lodash": "~4.17.21"
  },
  "devDependencies": {       // 开发依赖
    "typescript": "^5.0.0",
    "eslint": "^8.0.0"
  },
  "peerDependencies": {     // 同伴依赖（插件开发常用）
    "react": ">=16.8.0"
  },
  "optionalDependencies": { // 可选依赖
    "fsevents": "^2.3.2"
  },
  "bundleDependencies": [   // 打包依赖（npm pack 时会包含）
    "jquery"
  ]
}

脚本配置

3. scripts 详解

{
  "scripts": {
    "start": "node app.js",                // 启动命令
    "build": "tsc && vite build",          // 构建命令
    "test": "jest --coverage",             // 测试命令
    "prepublishOnly": "npm test",          // 发布前钩子
    "postinstall": "patch-package"         // 安装后钩子
  }
}

项目配置

4. 项目元数据

{
  "description": "项目描述",
  "keywords": ["keyword1", "keyword2"],  // npm 搜索关键词
  "license": "MIT",                      // 许可证
  "author": "John Doe <john@example.com>",
  "contributors": [
    {"name": "Jane Doe", "email": "jane@example.com"}
  ],
  "repository": {
    "type": "git",
    "url": "https://github.com/user/repo.git"
  },
  "homepage": "https://example.com",
  "bugs": {
    "url": "https://github.com/user/repo/issues"
  }
}

模块系统配置

5. 模块相关配置

{
  "type": "module",                     // 指定模块系统（"module"或"commonjs"）
  "main": "dist/index.js",              // CommonJS 入口
  "module": "dist/index.esm.js",        // ES Module 入口
  "exports": {                          // 条件导出（Node 12+）
    ".": {
      "import": "./dist/index.esm.js",
      "require": "./dist/index.cjs.js",
      "types": "./dist/index.d.ts"
    },
    "./features/*": "./dist/features/*.js"
  },
  "types": "dist/index.d.ts",           // TypeScript 类型声明文件
  "files": ["dist/**/*"],               // 包含在发布包中的文件
  "sideEffects": false                  // 是否包含副作用
}

发布配置

6. 发布相关配置

{
  "private": true,                      // 是否为私有包（禁止发布）
  "publishConfig": {
    "registry": "https://registry.npmjs.org",
    "access": "public"                  // 或 "restricted"（组织包）
  },
  "engines": {                          // 运行环境要求
    "node": ">=16.0.0",
    "npm": ">=8.0.0"
  },
  "os": ["darwin", "linux"],            // 支持的操作系统
  "cpu": ["x64", "arm64"]               // 支持的CPU架构
}

现代前端工具集成

7. 前端工具配置

{
  "browserslist": [                     // 浏览器兼容性配置
    "> 1%",
    "last 2 versions"
  ],
  "eslintConfig": {                     // ESLint 配置
    "extends": "eslint:recommended"
  },
  "stylelint": {                        // Stylelint 配置
    "extends": "stylelint-config-standard"
  },
  "jest": {                             // Jest 配置
    "testEnvironment": "jsdom"
  },
  "prettier": {                         // Prettier 配置
    "semi": false,
    "singleQuote": true
  }
}

工作区配置（Monorepo）

8. 工作区配置

{
  "workspaces": [                       // 工作区包目录
    "packages/*",
    "apps/*"
  ],
  "scripts": {
    "build:all": "npm run build -ws"    // -ws 在所有工作区运行
  }
}

高级配置

9. 其他重要配置

{
  "bin": {                              // 命令行工具入口
    "my-cli": "./bin/cli.js"
  },
  "man": ["./man/doc.1"],              // 手册页
  "config": {                           // 自定义配置
    "port": 8080
  },
  "husky": {                            // Git hooks
    "hooks": {
      "pre-commit": "lint-staged"
    }
  },
  "lint-staged": {                      // 提交时lint
    "*.{js,ts}": "eslint --fix"
  }
}

版本控制符号说明

符号	示例	说明
`^`	`^1.2.3`	允许次版本和修订号更新（1.x.x）
`~`	`~1.2.3`	只允许修订号更新（1.2.x）
无前缀	`1.2.3`	精确版本
`>`/`<`	`>1.2.3`	大于/小于指定版本
`*`	`*`	任何版本
`x`	`1.x`	主版本固定，其他任意

最佳实践建议

依赖管理：
- 使用 npm install --save-exact 获取精确版本
- 定期运行 npm outdated 检查过时依赖
脚本组织：
- 复杂脚本提取到单独的脚本文件
- 使用 pre 和 post 前缀定义生命周期脚本
安全性：
- 定期运行 npm audit 检查漏洞
- 使用 npm ci 替代 npm install 在CI环境中
性能优化：
- 合理使用 .npmignore 减少发布包体积
- 对于Monorepo项目，优先使用 pnpm 或 yarn workspaces
版本控制：
- 遵循语义化版本控制（SemVer）
- 使用 npm version 命令管理版本号

通过合理配置 package.json，可以显著提升项目的可维护性、协作效率和部署可靠性。