NPM 包发布完整实战方案

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：启用双因素认证（推荐）

1. 访问 https://npmjs.com → 登录 → Account Settings
2. 进入 “Authentication & Security” → “Two-factor Authentication”
3. 选择 “Authorization and publishing” 级别
4. 使用认证器应用扫描二维码完成设置
5. 重新登录：npm login（输入 2FA 验证码）

方案B：创建细粒度令牌（临时方案）

1. 访问 https://npmjs.com/settings/tokens
2. 创建 “Granular Access Token”
3. 权限配置：
   • Package: jiashicang-chat-sdk
   • 权限: Read and Write
   • 勾选: “Bypass two-factor authentication”
4. 使用令牌：

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 next

4.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 常见错误及解决

六、发布后清理阶段

6.1 恢复环境配置

# 清理认证令牌（如果使用了方案B）npmconfig delete //registry.npmjs.org/:_authToken# 验证配置恢复npmconfig list

6.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"=== 发布流程完成 ==="

八、关键成功要素

1. 认证必须：确保完成2FA配置或使用有效令牌
2. 包名唯一：jiashicang-chat-sdk 必须在npm上唯一
3. 版本管理：每次发布前更新版本号
4. 文件完整：确保dist目录包含所有必需文件
5. 网络通畅：确保可以正常访问registry.npmjs.org

按照此方案顺序执行，即可成功完成NPM包发布。