NPM 包发布完整实战方案

一、环境准备阶段

1.1 检查当前环境

# 确认当前登录用户
npm whoami
# 输出：jiangshiguang

# 检查当前 registry 配置
npm config get registry
# 期望：https://registry.npmjs.org/

1.2 验证包配置

# 检查 package.json 关键配置
cat package.json | grep -E '(name|version|main|files)'
# 确认：name、version、入口文件、发布文件列表正确

二、认证配置阶段

2.1 登录 npm 账户

# 执行登录（会打开浏览器完成认证）
npm login
# 注意：现代 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. 使用令牌：

   npm config set //registry.npmjs.org/:_authToken=你的令牌
   

三、预发布检查阶段

3.1 构建验证

# 清理并构建
npm run clean && npm run build

# 检查构建产物
ls -la dist/
# 确认：类型声明文件(.d.ts)和编译文件(.js)完整

3.2 发布前测试

# 干运行测试
npm publish --dry-run
# 检查：文件列表、包大小、依赖关系

四、正式发布阶段

4.1 执行发布命令

# 标准发布
npm publish

# 或发布到特定标签
npm publish --tag next

4.2 发布成功验证

# 检查包信息
npm info jiashicang-chat-sdk

# 验证版本
npm view jiashicang-chat-sdk versions

五、问题排查流程

5.1 遇到 403 错误时的排查步骤

# 1. 检查登录状态
npm whoami

# 2. 检查认证方式
npm config list | grep auth

# 3. 查看详细错误日志
cat F:\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）
npm config delete //registry.npmjs.org/:_authToken

# 验证配置恢复
npm config list

6.2 版本管理准备

# 为下一次发布更新版本
npm version patch  # 修复版本
npm version minor  # 小版本

七、完整执行脚本

#!/bin/bash
echo "=== NPM包发布流程开始 ==="

# 1. 环境检查
echo "1. 检查环境..."
npm whoami
npm config get registry

# 2. 认证配置
echo "2. 认证配置..."
npm login

# 3. 预发布检查
echo "3. 预发布检查..."
npm run build
npm publish --dry-run

# 4. 正式发布
echo "4. 执行发布..."
npm publish

# 5. 验证发布
echo "5. 验证发布..."
npm info jiashicang-chat-sdk

echo "=== 发布流程完成 ==="

八、关键成功要素

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

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