🔥package.json 终极指南：全属性清单（附详细注释），前端 / Node 开发者人手一份

子兮曰
154 阅读5分钟

开篇

不管你是刚接触前端 / Node 开发的新手，还是有一定经验的开发者，大概率都遇到过跟 package.json 相关的 “小麻烦”：新建项目时，对着满屏的属性字段发呆，不知道 “main” 和 “module” 该怎么区分填写；想配置自定义脚本，却在 “scripts” 里踩了参数格式的坑；碰到 “browserslist”“engines” 这类不常用的属性，只能反复切换窗口翻官方文档，还未必能找到清晰的使用说明。 其实不用这么麻烦 —— 今天这份内容，就是专门为解决这些问题而来的 “保姆级指南”，不仅把 package.json 里的所有核心属性都整理得明明白白，每个属性还附带详细注释，从基础的项目名称、版本号配置，到进阶的依赖管理、构建输出设置，甚至是发布 npm 包时需要用到的特殊属性，全都覆盖到了，几乎能满足 99% 的项目配置场景，新手能跟着直接填，老开发者也能省掉反复查资料的时间。

一、基础信息属性

  1. name - 项目名称

    "name": "my-project"

    必须是小写字母、数字、连字符或下划线，不能有空格

  2. version - 版本号

    "version": "1.0.0"

    遵循语义化版本规范（major.minor.patch）

  3. description - 项目描述

    "description": "一个基于React的前端项目"

    项目的简短描述，用于npm搜索和展示

  4. keywords - 关键词数组

    "keywords": ["react", "typescript", "webpack"]

    帮助用户在npm上发现你的包

  5. author - 作者信息

    "author": "张三 <zhangsan@email.com> (https://github.com/zhangsan)"

    可以包含姓名、邮箱和网址

  6. contributors - 贡献者列表

    "contributors": [
  "李四 <lisi@email.com>",
  "王五 <wangwu@email.com>"
]

    项目的其他贡献者

  7. license - 许可证

    "license": "MIT"

    项目的开源许可证类型

  8. homepage - 项目主页

    "homepage": "https://github.com/user/project#readme"

    项目的主页URL

二、文件相关属性

  1. main - 主入口文件

    "main": "dist/index.js"

    项目的入口文件，require('package-name')时加载的文件

  2. browser - 浏览器环境入口

    "browser": "dist/browser.js"

    专门为浏览器环境准备的入口文件

  3. module - ES模块入口

    "module": "dist/index.esm.js"

    ES模块格式的入口文件

  4. types - TypeScript类型定义

    "types": "dist/index.d.ts"

    TypeScript类型声明文件

  5. typings - TypeScript类型定义（types的别名）

    "typings": "dist/index.d.ts"

    与types相同，为了向后兼容

  6. bin - 可执行文件

    "bin": {
  "my-cli": "./bin/cli.js"
}

    包安装时创建的命令行工具

  7. man - 手册页

    "man": "./man/doc.1"

    指定man手册页文件

  8. directories - 目录结构

    "directories": {
  "lib": "src",
  "bin": "bin",
  "man": "man",
  "doc": "docs",
  "example": "examples"
}

    指定包的各种目录结构

  9. files - 包含的文件

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

    发布到npm时包含的文件列表

  10. repository - 代码仓库

    "repository": {
  "type": "git",
  "url": "https://github.com/user/repo.git",
  "directory": "packages/my-package"
}

    代码仓库信息

  11. bugs - 问题反馈

    "bugs": {
  "url": "https://github.com/user/repo/issues",
  "email": "bugs@example.com"
}

    问题反馈的地址

三、依赖相关属性

  1. dependencies - 生产依赖

    "dependencies": {
  "react": "^18.0.0",
  "lodash": "^4.17.21"
}

    项目运行时必需的依赖包

  2. devDependencies - 开发依赖

    "devDependencies": {
  "jest": "^29.0.0",
  "eslint": "^8.0.0"
}

    只在开发时需要的依赖包

  3. peerDependencies - 对等依赖

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

    要求宿主环境安装的依赖

  4. optionalDependencies - 可选依赖

    "optionalDependencies": {
  "fsevents": "^2.3.2"
}

    可选的依赖包，安装失败不会影响主要功能

  5. bundledDependencies - 捆绑依赖

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

    发布时一起打包的依赖包

四、脚本相关属性

  1. scripts - 脚本命令

    "scripts": {
  "start": "node server.js",
  "test": "jest",
  "build": "webpack --mode production"
}

    定义npm run可执行的脚本命令

  2. config - 配置参数

    "config": {
  "port": 3000,
  "apiUrl": "https://api.example.com"
}

    可以在脚本中使用的配置参数

五、环境要求属性

  1. engines - 引擎要求

    "engines": {
  "node": ">=16.0.0",
  "npm": ">=8.0.0",
  "yarn": ">=1.22.0"
}

    运行环境要求

  2. os - 操作系统要求

    "os": ["darwin", "linux", "win32"]

    支持的操作系统

  3. cpu - CPU架构要求

    "cpu": ["x64", "arm64"]

    支持的CPU架构

  4. private - 私有包

    "private": true

    设置为true防止意外发布到npm

六、发布相关属性

  1. publishConfig - 发布配置

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

    发布到npm时的配置

  2. workspaces - 工作区配置

    "workspaces": [
  "packages/*",
  "apps/*"
]

    monorepo项目的工作区配置

七、其他属性

  1. preferGlobal - 偏好全局安装

    "preferGlobal": true

    建议用户全局安装此包

  2. style - CSS样式入口

    "style": "dist/style.css"

    主要的CSS样式文件

  3. jspm - JSPM配置

    "jspm": {
  "main": "index",
  "format": "esm"
}

    JSPM包管理器的配置

  4. esnext - ES下一代语法

    "esnext": {
  "main": "src/index.js",
  "browser": "src/index.browser.js"
}

    ES下一代语法的入口文件

  5. unpkg - UNPKG CDN入口

    "unpkg": "dist/umd/index.js"

    UNPKG CDN使用的入口文件

  6. jsdelivr - jsDelivr CDN入口

    "jsdelivr": "dist/umd/index.js"

    jsDelivr CDN使用的入口文件

  7. sideEffects - 副作用标记

    "sideEffects": false

    标记包是否有副作用，用于tree shaking

  8. type - 模块类型

    "type": "module"

    指定包使用ES模块（module）或CommonJS（commonjs）

这个清单涵盖了package.json的所有标准属性，每个属性都有详细的解释和示例用法

结语

看到这里，你已经拿到了一份能应对 99% 项目配置场景的 package.json “说明书”—— 从最基础的 “name”“version”，到容易混淆的 “dependencies” 与 “devDependencies”，再到能控制模块导出的 “exports”、适配不同浏览器的 “browserslist”，每个属性的作用、填写规则和使用场景，都有清晰的注释和说明。后续不管你是开发个人小项目、参与团队协作，还是准备发布自己的 npm 包，遇到 package.json 配置问题时，都能直接对照这份内容快速解决。建议把它存好，下次不用再翻零散的文档；如果你的项目里有一些特殊配置场景，或者用到了文中没提到的属性，也欢迎在评论区分享，咱们一起把这份 “指南” 补得更全面～

avatar
文章
阅读
粉丝