package.json 配置

antkang
130 阅读5分钟

package.json 配置

{
  // === 基本信息字段 ===
  "name": "@scope/package-name", // 项目名称，可以带作用域(@scope/)，必须唯一
  "version": "1.0.0", // 版本号，遵循语义化版本规范（major.minor.patch）
  "description": "项目的详细描述信息", // 项目描述，会显示在npm搜索结果中
  "keywords": ["react", "vue", "frontend", "ui"], // 关键词数组，用于npm搜索和分类
  "homepage": "https://example.com", // 项目主页URL
  "bugs": { // 问题反馈信息
    "url": "https://github.com/user/repo/issues", // 问题跟踪URL
    "email": "support@example.com" // 问题反馈邮箱
  },
  "license": "MIT", // 开源许可证类型
  "author": { // 作者信息（完整格式）
    "name": "作者姓名",
    "email": "author@example.com",
    "url": "https://author-website.com"
  },
  "contributors": [ // 贡献者列表
    {
      "name": "贡献者1",
      "email": "contributor1@example.com"
    }
  ],
  "maintainers": [ // 维护者列表
    {
      "name": "维护者1",
      "email": "maintainer1@example.com"
    }
  ],

  // === 文件和目录配置 ===
  "main": "lib/index.js", // CommonJS模块入口文件
  "module": "es/index.js", // ES Module入口文件
  "browser": "dist/index.umd.js", // 浏览器环境入口文件
  "types": "lib/index.d.ts", // TypeScript类型声明文件
  "typings": "lib/index.d.ts", // TypeScript类型声明文件（types的别名）
  "exports": { // Node.js模块导出映射（新标准）
    ".": {
      "import": "./es/index.js",
      "require": "./lib/index.js",
      "browser": "./dist/index.umd.js"
    },
    "./package.json": "./package.json"
  },
  "files": [ // 发布到npm时包含的文件和目录
    "lib",
    "es",
    "dist",
    "src",
    "README.md",
    "LICENSE"
  ],
  "directories": { // 目录结构说明
    "lib": "./lib", // 库文件目录
    "bin": "./bin", // 可执行文件目录
    "man": "./man", // 手册页目录
    "doc": "./docs", // 文档目录
    "example": "./examples", // 示例目录
    "test": "./test" // 测试目录
  },
  "bin": { // 可执行文件定义
    "my-cli": "./bin/cli.js"
  },
  "man": "./man/my-package.1", // 手册页文件

  // === 项目配置 ===
  "private": true, // 私有项目，防止意外发布到npm
  "publishConfig": { // 发布配置
    "registry": "https://npm.example.com", // 自定义npm仓库
    "access": "public" // 发布访问级别：public/restricted
  },
  "workspaces": [ // Monorepo工作区配置
    "packages/*",
    "apps/*"
  ],
  "type": "module", // 模块类型：module(ESM) 或 commonjs(CJS)

  // === 脚本命令 ===
  "scripts": { // 可执行的npm脚本
    "dev": "vite", // 开发服务器
    "serve": "vite preview", // 预览构建结果
    "build": "vite build", // 生产构建
    "build:dev": "vite build --mode development", // 开发模式构建
    "build:prod": "vite build --mode production", // 生产模式构建
    "test": "jest", // 运行测试
    "test:watch": "jest --watch", // 监听模式测试
    "test:coverage": "jest --coverage", // 生成覆盖率报告
    "lint": "eslint . --ext .js,.jsx,.ts,.tsx,.vue", // 代码检查
    "lint:fix": "eslint . --ext .js,.jsx,.ts,.tsx,.vue --fix", // 自动修复代码问题
    "format": "prettier --write .", // 代码格式化
    "type-check": "tsc --noEmit", // TypeScript类型检查
    "docs": "jsdoc -d docs src/", // 生成文档
    "clean": "rimraf dist lib es", // 清理构建文件
    "prepare": "husky install", // Git hooks安装
    "prepublishOnly": "npm run build", // 发布前构建
    "postinstall": "echo 'Installation complete'", // 安装后执行
    "precommit": "lint-staged", // 提交前检查
    "release": "standard-version", // 版本发布
    "deploy": "gh-pages -d dist" // 部署到GitHub Pages
  },

  // === 依赖管理 ===
  "dependencies": { // 生产环境依赖
    "react": "^18.2.0", // React框架
    "react-dom": "^18.2.0", // React DOM渲染器
    "vue": "^3.3.0", // Vue.js框架
    "axios": "^1.4.0", // HTTP请求库
    "lodash": "^4.17.21", // 工具函数库
    "moment": "^2.29.0", // 日期处理库
    "classnames": "^2.3.0" // CSS类名工具
  },
  "devDependencies": { // 开发环境依赖
    "@types/node": "^20.0.0", // Node.js类型定义
    "@types/react": "^18.2.0", // React类型定义
    "@typescript-eslint/eslint-plugin": "^5.60.0", // TypeScript ESLint插件
    "@typescript-eslint/parser": "^5.60.0", // TypeScript ESLint解析器
    "@vitejs/plugin-react": "^4.0.0", // Vite React插件
    "@vitejs/plugin-vue": "^4.0.0", // Vite Vue插件
    "eslint": "^8.43.0", // JavaScript/TypeScript代码检查
    "eslint-config-prettier": "^8.8.0", // Prettier与ESLint集成
    "eslint-plugin-react": "^7.32.0", // React ESLint插件
    "eslint-plugin-vue": "^9.15.0", // Vue ESLint插件
    "husky": "^8.0.3", // Git hooks管理
    "jest": "^29.5.0", // 测试框架
    "lint-staged": "^13.2.0", // Git暂存文件检查
    "prettier": "^2.8.8", // 代码格式化工具
    "typescript": "^5.1.0", // TypeScript编译器
    "vite": "^4.3.0", // 构建工具
    "vitest": "^0.32.0" // 测试运行器
  },
  "peerDependencies": { // 同等依赖（宿主项目需要提供）
    "react": ">=16.8.0", // 要求宿主项目提供的React版本
    "react-dom": ">=16.8.0" // 要求宿主项目提供的React DOM版本
  },
  "peerDependenciesMeta": { // 同等依赖元数据
    "react": {
      "optional": true // 标记为可选的同等依赖
    }
  },
  "optionalDependencies": { // 可选依赖（安装失败不影响整体）
    "fsevents": "^2.3.0" // macOS文件系统事件（仅macOS需要）
  },
  "bundledDependencies": [ // 打包时包含的依赖
    "lodash"
  ],
  "overrides": { // 依赖版本覆盖（npm 8.3+）
    "semver": "^7.0.0"
  },
  "resolutions": { // 依赖版本解析（Yarn专用）
    "lodash": "^4.17.21"
  },

  // === 环境和兼容性 ===
  "engines": { // 运行环境版本要求
    "node": ">=16.0.0", // Node.js最低版本
    "npm": ">=8.0.0", // npm最低版本
    "yarn": ">=1.22.0" // Yarn最低版本
  },
  "os": ["linux", "darwin", "win32"], // 支持的操作系统
  "cpu": ["x64", "arm64"], // 支持的CPU架构
  "browserslist": [ // 目标浏览器配置
    "> 1%", // 全球使用率大于1%
    "last 2 versions", // 每个浏览器的最后2个版本
    "not dead", // 排除不再维护的浏览器
    "not ie 11" // 排除IE11
  ],

  // === 代码仓库信息 ===
  "repository": { // 代码仓库信息
    "type": "git", // 版本控制类型
    "url": "https://github.com/user/repo.git", // 仓库URL
    "directory": "packages/my-package" // Monorepo中的子目录
  },
  "funding": [ // 资金支持信息
    {
      "type": "github", // 资金平台类型
      "url": "https://github.com/sponsors/username"
    },
    {
      "type": "opencollective",
      "url": "https://opencollective.com/project"
    }
  ],

  // === 工具配置 ===
  "eslintConfig": { // ESLint配置
    "extends": ["@vue/typescript/recommended", "prettier"],
    "rules": {
      "no-console": "warn"
    }
  },
  "prettier": { // Prettier配置
    "semi": true,
    "singleQuote": true,
    "tabWidth": 2
  },
  "stylelint": { // Stylelint配置
    "extends": ["stylelint-config-standard"]
  },
  "jest": { // Jest测试配置
    "testEnvironment": "jsdom",
    "setupFilesAfterEnv": ["<rootDir>/src/setupTests.js"]
  },
  "babel": { // Babel配置
    "presets": ["@babel/preset-env", "@babel/preset-react"]
  },
  "postcss": { // PostCSS配置
    "plugins": {
      "autoprefixer": {}
    }
  },
  "lint-staged": { // Git暂存文件检查配置
    "*.{js,jsx,ts,tsx,vue}": ["eslint --fix", "prettier --write"],
    "*.{css,scss,less}": ["stylelint --fix", "prettier --write"],
    "*.{md,json}": ["prettier --write"]
  },
  "husky": { // Husky Git hooks配置
    "hooks": {
      "pre-commit": "lint-staged",
      "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
    }
  },
  "commitlint": { // 提交信息检查配置
    "extends": ["@commitlint/config-conventional"]
  },

  // === 构建和打包配置 ===
  "sideEffects": false, // 标记包是否有副作用（用于tree-shaking）
  "unpkg": "dist/index.umd.js", // unpkg CDN入口文件
  "jsdelivr": "dist/index.umd.js", // jsdelivr CDN入口文件
  "esnext": "src/index.js", // 未转译的ES next源码入口

  // === 自定义字段 ===
  "config": { // 自定义配置
    "port": 3000,
    "theme": "dark"
  },
  "volta": { // Volta Node.js版本管理
    "node": "18.16.0",
    "npm": "9.5.1"
  },
  "packageManager": "npm@9.5.1" // 指定包管理器版本
}

版本号规则说明

语义化版本格式

  • MAJOR.MINOR.PATCH (如: 1.2.3)
  • MAJOR: 不兼容的API修改
  • MINOR: 向后兼容的功能新增
  • PATCH: 向后兼容的问题修正

版本范围符号

  • ^1.2.3: 兼容版本，允许 >=1.2.3 <2.0.0
  • ~1.2.3: 合理版本，允许 >=1.2.3 <1.3.0
  • 1.2.3: 精确版本，固定版本号
  • >=1.2.3: 大于等于指定版本
  • <1.2.3: 小于指定版本
  • 1.2.x: 通配符，匹配 1.2.*
  • *: 任意版本
  • latest: 最新版本
  • alpha/beta/rc: 预发布版本

字段优先级和重要性

🔴 必需字段

  • name: 包名称（发布时必需）
  • version: 版本号（发布时必需）

🟡 重要字段

  • description: 包描述
  • main/module/browser: 入口文件
  • scripts: 脚本命令
  • dependencies: 生产依赖
  • devDependencies: 开发依赖

🟢 推荐字段

  • keywords: 搜索关键词
  • author: 作者信息
  • license: 许可证
  • repository: 代码仓库
  • engines: 环境要求

⚪ 可选字段

  • homepage: 项目主页
  • bugs: 问题反馈
  • funding: 资金支持
  • 各种工具配置字段
avatar
文章
阅读
粉丝