版本发布

package.json 必要字段

• 包名，必须是全局唯一
• 如果是 Scoped 包，格式为 @scope/包名
• 包名必须符合以下规则：
  • 只能包含小写字母、数字、连字符（-）
  • 不允许以 . 或 _ 开头

• 当前包的版本号，必须符合 语义化版本规范 (SemVer)
• 格式：主版本号.次版本号.修订号，如 1.0.0

• 包的入口文件路径（相对于项目根目录）
• 如果是模块化项目，可用 exports 字段定义多个入口点

• 指定开源许可证类型（如 MIT、ISC）
• 如果不想开源，将其设置为 UNLICENSED，否则可能报错。

• 明确列出需要发布的文件或目录，避免无关内容被上传。例如：测试文件

示例：

"files": [
    "dist",
    "es",
    "lib",
    "README.md"
]

• 自定义发布时的配置，例如：
  • registry：指定发布的注册表地址
  • access: 公开性设置（public 或 restricted）

示例：

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

package.json 推荐字段

对包的简短描述，用于 NPM 网站显示

关键字数组，方便用户在 NPM 搜索中找到你的包

包的代码仓库地址。

示例：

"repository": {
  "type": "git",
  "url": "https://github.com/your-username/your-repo.git"
}

包的官网地址

提交 Bug 报告的地址。

示例：

"bugs": {
  "url": "https://github.com/your-username/your-repo/issues"
}

指定支持的 Node.js 或 npm 版本。

示例：

"engines": {
  "node": ">=14",
  "npm": ">=6"
}

常见问题

版本冲突

You cannot publish over the previously published versions.

原因：说明版本已经存在，请及时更新版本。

权限不足

You do not have permission to publish this package.

原因： 当前用户没有发布权限

文件超大

npm ERR! code ENEEDAUTH 或 Tarball too large.

原因： 未正确设置 files 字段或 .npmignore 文件

注册表问题

npm ERR! 404 Not Found 或 npm ERR! ENOTFOUND

原因： 注册表配置有误或未联网

npm publish 的执行流程

1、检查当前目录

• 确保当前目录包含 package.json 文件，否则会报错。
• 检查项目结构，忽略不必要的文件（使用 .npmignore 或 .gitignore）,以便减少上传体积

2、验证 package.json

• 确保 package.json 中的必要字段正确且有效

3、运行钩子脚本

• 执行 scripts 中定义的钩子脚本

例如：

prepare：安装时和发布前运行（常用于打包构建）
prepublishOnly：仅发布前运行（不会在 npm install 中触发）
postpublish：发布后运行（用于通知、清理等）

4、检查版本号

• 对比 package.json 中的 version 和远程注册表的版本，如果当前版本已存在，npm publish 会被拒绝。

5、打包项目

将所有符合条件的文件打包成 .tgz 文件，准备上传.

6、权限验证

• 确保当前用户拥有发布到该 package 或 scope 的权限

7、上传到 npm

默认上传到 https://registry.npmjs.org，如果 .npmrc 中配置了其他注册表地址，则上传到自定义注册表。 成功上传后，包会立即可用。

最佳实践

• 优化包的大小(可执行npm pack --dry-run检查发表内容)
• 自动化发布流程
• 确保代码质量
• scoped 包名 (对团队开发项目，建议使用 Scoped 包名（如 @your-scope/package-name）, 便于管理和权限控制)