貌似很多开发者干了很多年，对package.json都不够了解，现在通过这篇文章和大家一起来认识一下package.json中的相关知识。
一、package.json的核心作用在了解具体字段前，我们先明确package.json的本质：它是一个JSON格式的项目元数据文件，主要用于：
描述项目基本信息：名称、版本、作者、许可证等声明依赖关系：项目运行和开发所需的第三方包定义脚本命令：通过npm run执行的脚本（如dev、build）配置工具行为：告诉打包工具、测试框架等如何处理项目发布配置：当项目作为npm包发布时，控制发布内容和行为简单说，package.json是项目的"说明书"，既是给开发者看的文档，也是给工具链读的配置文件。
二、标准字段：npm官方定义的核心属性标准字段是npm规范中明确定义的属性，大部分具有跨工具的通用性。我们按重要性分为核心字段、依赖管理字段、脚本与配置字段和发布相关字段四类。
1. 核心元信息字段（必填/关键）这些字段描述项目的基本标识信息，其中name和version是发布npm包时的必填项。
字段名类型是否必填描述注意事项name字符串是（发布时）项目名称，作为npm包发布时的唯一标识不能包含大写字母、空格，建议用kebab-case（如my-project）；长度≤214字符version字符串是（发布时）版本号，必须符合语义化版本（SemVer）规范格式为MAJOR.MINOR.PATCH（如1.2.3）；发布后不能修改同版本内容description字符串否项目描述，会显示在npm官网和npm info命令结果中简洁明了，便于他人理解项目用途author字符串/对象否项目作者，格式可为"Name
{
"name": "react-hooks-utils",
"version": "2.3.0",
"description": "A collection of useful React hooks",
"author": "John Doe
"license": "MIT",
"private": false
}
2. 依赖管理字段（核心功能）这些字段定义项目依赖的第三方包，是package.json最常用的功能之一。
字段名类型描述安装命令示例dependencies对象项目运行时依赖（如React、Lodash），生产环境必需npm install reactdevDependencies对象项目开发时依赖（如Webpack、ESLint），生产环境不需要npm install -D webpackpeerDependencies对象同伴依赖，声明项目需要的宿主环境版本（如UI组件库依赖特定React版本）无需手动安装，由宿主项目提供peerDependenciesMeta对象配置peer依赖的可选性（如{"react": {"optional": true}}）配合peerDependencies使用optionalDependencies对象可选依赖，安装失败不会导致整个安装过程失败npm install --save-optional fseventsbundledDependencies数组发布时需要打包的依赖（极少用，通常用dependencies）需手动列出包名数组关键区别：
dependencies vs devDependencies：前者会被npm install --production安装，后者不会；打包工具（如Webpack）默认会将dependencies的内容纳入产物。peerDependencies的典型场景：UI组件库（如Ant Design）声明对React的版本要求，确保使用者的React版本兼容。示例：
{
"dependencies": {
"react": "^18.0.0",
"react-dom": "^18.0.0"
},
"devDependencies": {
"@types/react": "^18.0.0",
"vite": "^4.0.0"
},
"peerDependencies": {
"react": ">=17.0.0"
},
"peerDependenciesMeta": {
"react": { "optional": false }
}
}
3. 脚本与配置字段这些字段控制项目的脚本命令和工具链行为。
字段名类型描述示例scripts对象定义可通过npm run
内置钩子：如prebuild（build前执行）、postbuild（build后执行），无需显式调用环境变量：可访问NODE_ENV等环境变量，或通过cross-env跨平台设置自定义变量简写命令：npm start等价于npm run start，npm test等价于npm run test示例：
{
"scripts": {
"dev": "vite",
"prebuild": "eslint .",
"build": "vite build",
"postbuild": "echo Build completed!",
"test": "vitest run"
},
"config": {
"apiUrl": "https://api.example.com"
},
"engines": {
"node": ">=18.0.0"
}
}
4. 发布与文件控制字段这些字段控制npm包的发布行为和文件包含/排除规则。
字段名类型描述注意事项main字符串包的入口文件路径，require('包名')时会加载该文件默认为index.js；ESM项目可用module字段（非标准，但被广泛支持）module字符串ESM模块入口（非标准，被Rollup、Webpack等工具支持）用于区分CommonJS和ESM入口browser字符串/对象浏览器环境的入口文件，用于替代main（适用于同时支持Node和浏览器的包）可指定{"main": "./browser.js"}，工具会优先使用浏览器版本files数组发布时需要包含的文件/目录列表（白名单）支持通配符（如"dist/*"）；与.npmignore文件作用相反（黑名单）bin字符串/对象定义可执行命令，发布后会被链接到npm的全局bin目录如{"my-cli": "./bin/cli.js"}，安装后可直接运行my-cli命令types/typings字符串TypeScript类型定义文件路径默认为index.d.ts，用于提供类型提示repository字符串/对象代码仓库地址，会显示在npm官网格式如"github:username/repo"或{"type": "git", "url": "..."}homepage字符串项目主页URL（如文档地址）-bugs字符串/对象问题反馈地址（如GitHub Issues）如{"url": "https://github.com/xxx/issues"}示例：
{
"main": "dist/index.cjs",
"module": "dist/index.mjs",
"browser": "dist/browser.js",
"files": ["dist", "README.md", "LICENSE"],
"bin": {
"calc": "./bin/calc.js"
},
"types": "dist/index.d.ts",
"repository": "github:my-org/calculator",
"homepage": "https://my-org.github.io/calculator/",
"bugs": {
"url": "https://github.com/my-org/calculator/issues"
}
}
三、非标准字段：工具链与生态扩展非标准字段（也称"自定义字段"）并非npm规范定义，但被各类工具、框架广泛采用，用于配置特定功能。它们通常有两种形式：
工具特定字段：如eslintConfig、jest，由对应工具直接读取命名空间字段：以特定前缀开头（如vue、next），用于框架配置完全自定义字段：通常以_开头（如_myProjectConfig），避免冲突1. 构建工具相关字段字段名关联工具描述browserlistautoprefixer、Babel定义目标浏览器范围（如["last 2 versions", "not dead"]）babelBabelBabel配置（替代.babelrc文件）webpackWebpackWebpack配置（通常用于简单配置，复杂配置仍用单独文件）viteViteVite配置选项（如{"resolve": {"alias": {"@": "./src"}}}）rollupRollupRollup打包配置2. 代码质量与测试工具字段字段名关联工具描述eslintConfigESLintESLint配置（规则、解析器等）prettierPrettierPrettier格式化配置（如{"singleQuote": true}）jestJestJest测试框架配置vitestVitestVitest测试框架配置lint-stagedlint-staged定义Git暂存区文件的lint规则（如{"*.js": ["eslint --fix"]}）3. 框架与库特定字段字段名关联框架/库描述vueVue.jsVue CLI项目配置（如{"version": 3, "css": {"extract": false}}）nextNext.jsNext.js配置（如{"reactStrictMode": true}）nuxtNuxt.jsNuxt.js配置（如{"srcDir": "src/", "generate": {"dir": "dist"}}）reactReact极少用，某些工具用于指定React版本兼容信息workspacesnpm/yarn/pnpmMonorepo工作区配置（如["packages/*"]）4. 其他常用非标字段字段名用途funding项目资助信息（如{"type": "github", "url": "https://github.com/sponsors/xxx"}）keywords项目关键词数组（如["react", "hooks", "utils"]），用于npm搜索publishConfig发布配置（如{"registry": "https://custom-registry.com"}），覆盖默认发布行为sideEffects告知Webpack等工具哪些文件有副作用（不能被Tree-Shaking移除），如["*.css"]非标字段示例：
{
"browserlist": ["last 2 versions", "not ie <= 11"],
"eslintConfig": {
"extends": ["eslint:recommended", "plugin:react/recommended"],
"parserOptions": { "ecmaVersion": 2020 }
},
"prettier": {
"singleQuote": true,
"trailingComma": "es5"
},
"vite": {
"server": { "port": 3000 },
"build": { "target": "es2015" }
},
"workspaces": ["packages/*"],
"keywords": ["vite", "react", "template"],
"publishConfig": {
"access": "public"
}
}
四、注意事项必选字段检查：
发布到npm的包必须包含name和version内部项目建议设置"private": true，防止意外发布至少添加description和keywords，提升包的可发现性依赖管理原则：
区分dependencies和devDependencies，避免生产环境包含冗余依赖谨慎使用peerDependencies，明确声明版本范围（避免过宽或过窄）不要将node_modules目录提交到Git，通过package-lock.json锁定版本非标字段规范：
自定义字段建议添加项目前缀（如myAppConfig），避免与工具字段冲突复杂配置优先使用单独文件（如.eslintrc.js），而非塞进package.json了解工具对字段的支持情况（如module字段并非所有工具都兼容）版本号管理：
严格遵循语义化版本（SemVer），避免随意升级主版本使用~和^控制版本范围（如~1.2.3允许补丁更新，^1.2.3允许次版本更新）五、总结package.json是项目的"神经中枢"，既包含描述项目的元数据，也承载着工具链的配置规则。理解标准字段能帮助你正确管理依赖和发布流程，而掌握非标字段则能让你更高效地使用各类开发工具。
随着前端生态的发展，package.json的功能还在不断扩展，但核心始终是"描述项目、连接工具"。合理配置每个字段，不仅能提升项目的可维护性，也是前端工程化能力的重要体现。
最后，推荐两个实用工具帮助你管理package.json：
npm-package-json-lint：检查package.json的规范性syncpack：在Monorepo中同步依赖版本希望本文能帮你彻底搞懂package.json，让你的项目配置更加规范高效！