NPM 包发布完整实战方案
一、环境准备阶段
1.1 检查当前环境
# 确认当前登录用户npmwhoami# 输出：jiangshiguang# 检查当前 registry 配置npmconfig get registry# 期望：https://registry.npmjs.org/1.2 验证包配置
# 检查 package.json 关键配置catpackage.json|grep-E'(name|version|main|files)'# 确认：name、version、入口文件、发布文件列表正确二、认证配置阶段
2.1 登录 npm 账户
# 执行登录（会打开浏览器完成认证）npmlogin# 注意：现代 npm 要求双因素认证2.2 解决 403 认证错误（核心问题）
问题现象：
npm error 403 Forbidden - Two-factor authentication required解决方案（二选一）：
方案A：启用双因素认证（推荐）
- 访问 https://npmjs.com → 登录 → Account Settings
- 进入 “Authentication & Security” → “Two-factor Authentication”
- 选择 “Authorization and publishing” 级别
- 使用认证器应用扫描二维码完成设置
- 重新登录：
npm login（输入 2FA 验证码）
方案B：创建细粒度令牌（临时方案）
- 访问 https://npmjs.com/settings/tokens
- 创建 “Granular Access Token”
- 权限配置：
- Package: jiashicang-chat-sdk
- 权限: Read and Write
- 勾选: “Bypass two-factor authentication”
- 使用令牌：
npmconfigset//registry.npmjs.org/:_authToken=你的令牌三、预发布检查阶段
3.1 构建验证
# 清理并构建npmrun clean&&npmrun build# 检查构建产物ls-la dist/# 确认：类型声明文件(.d.ts)和编译文件(.js)完整3.2 发布前测试
# 干运行测试npmpublish --dry-run# 检查：文件列表、包大小、依赖关系四、正式发布阶段
4.1 执行发布命令
# 标准发布npmpublish# 或发布到特定标签npmpublish --tag next4.2 发布成功验证
# 检查包信息npminfo jiashicang-chat-sdk# 验证版本npmview jiashicang-chat-sdk versions五、问题排查流程
5.1 遇到 403 错误时的排查步骤
# 1. 检查登录状态npmwhoami# 2. 检查认证方式npmconfig list|grepauth# 3. 查看详细错误日志catF:\tools\nvm\nvm\node_cache\_logs\2025-12-13T12_55_49_519Z-debug-0.log# 4. 根据错误信息选择解决方案：# - "Two-factor authentication required" → 启用2FA# - "Package name already exists" → 修改包名或版本# - "Insufficient permissions" → 检查包所有权5.2 常见错误及解决
| 错误类型 | 现象 | 解决方案 |
|---|---|---|
| E403 | 认证失败 | 启用2FA或使用细粒度令牌 |
| E404 | 包不存在 | 检查包名拼写 |
| E401 | 未授权 | 重新登录npm |
| E402 | 需要付费账户 | 检查包是否为私有 |
六、发布后清理阶段
6.1 恢复环境配置
# 清理认证令牌（如果使用了方案B）npmconfig delete //registry.npmjs.org/:_authToken# 验证配置恢复npmconfig list6.2 版本管理准备
# 为下一次发布更新版本npmversion patch# 修复版本npmversion minor# 小版本七、完整执行脚本
#!/bin/bashecho"=== NPM包发布流程开始 ==="# 1. 环境检查echo"1. 检查环境..."npmwhoaminpmconfig get registry# 2. 认证配置echo"2. 认证配置..."npmlogin# 3. 预发布检查echo"3. 预发布检查..."npmrun buildnpmpublish --dry-run# 4. 正式发布echo"4. 执行发布..."npmpublish# 5. 验证发布echo"5. 验证发布..."npminfo jiashicang-chat-sdkecho"=== 发布流程完成 ==="八、关键成功要素
- 认证必须：确保完成2FA配置或使用有效令牌
- 包名唯一：jiashicang-chat-sdk 必须在npm上唯一
- 版本管理：每次发布前更新版本号
- 文件完整：确保dist目录包含所有必需文件
- 网络通畅：确保可以正常访问registry.npmjs.org
按照此方案顺序执行，即可成功完成NPM包发布。
