Claude Code NPM 包发布命令

Claude Code NPM 包发布命令

介绍

这是一个完整的自定义 NPM 发包自动化流程工具，只需一条 /npm:publish 指令，就能完成 版本选择、项目构建、变更日志更新、发布到 npm/cnpm 以及 Git 同步 等全流程操作。

它支持交互式选择或直接传参，涵盖标准版本（patch、minor、major）和预发布版本（alpha、beta、rc 等），并内置环境检查、失败回滚、权限验证和标签管理。
无论是日常的小修补，还是正式发行大版本，你都能用它快速、安全地完成从代码到线上包的整个发布过程。

存放位置

~/.claude/commands/npm/publish.md

注意事项

当前指令优先使用 cnpm，可根据需求进行适当调整。

NPM 包发布命令

---

description: 完整的 npm 包发布工作流程，支持版本选择、构建、变更日志更新和发布
argument-hint: [version-type] [prerelease-id]
allowed-tools: [Bash, Read, LS, Edit, Grep]

NPM 包发布命令

自动化 npm 包发布流程，包括版本更新、构建、变更日志更新、发布和 Git 同步。

使用方法:

/npm:publish [version-type] [prerelease-id]

参数:

• version-type (可选): 版本类型
  • 标准版本: patch, minor, major
  • 预发布版本: prerelease, prepatch, preminor, premajor
• prerelease-id (可选): 预发布标识符 (alpha, beta, rc)

工作流程:

1. 环境检查

   • 检查是否在 Node.js 项目中 (package.json 存在)
   • 验证 Git 工作目录状态 (确保工作目录干净)
   • 确保 cnpm 工具可用性 (优先使用 cnpm，不可用时回退到 npm)
   • 验证 cnpm/npm 登录状态

2. 版本选择

   • 如果未提供参数，显示交互式选择菜单
   • 显示当前版本和预期新版本
   • 用户确认版本更新

3. 构建流程

   • 自动检测 package.json 中的构建脚本 (build, compile, dist, prepare 等)
   • 如果找到构建脚本则询问是否执行，找不到则跳过构建步骤

4. 版本更新

   • 使用 npm version 命令更新 package.json 中的版本号
   • 自动生成对应的 Git 标签和提交

5. 变更日志管理

   • 检测 CHANGELOG.md 文件是否存在
   • 如果不存在则自动创建标准格式的变更日志文件
   • 自动更新版本记录和发布时间到变更日志

6. 包发布

   • 优先使用 cnpm publish 发布到 npm 仓库
   • cnpm 不可用时自动回退使用 npm publish
   • 发布前进行最终确认，处理发布权限和网络错误

7. Git 同步

   • 推送版本提交和标签到远程仓库
   • 确保版本信息在本地和远程仓库完整同步

使用示例:

• /npm:publish - 交互式选择版本类型
• /npm:publish patch - 发布补丁版本
• /npm:publish minor - 发布小版本更新
• /npm:publish major - 发布主版本更新
• /npm:publish prerelease alpha - 发布 alpha 预发布版本
• /npm:publish prepatch beta - 发布 beta 预发布补丁版本

版本类型说明:

标准版本:

• patch: 补丁版本 (1.0.0 → 1.0.1) - bug 修复
• minor: 小版本 (1.0.0 → 1.1.0) - 新功能，向后兼容
• major: 主版本 (1.0.0 → 2.0.0) - 破坏性更改

预发布版本:

• prerelease: 基于当前版本的预发布 (1.0.0 → 1.0.0-alpha.0)
• prepatch: 预发布补丁 (1.0.0 → 1.0.1-alpha.0)
• preminor: 预发布小版本 (1.0.0 → 1.1.0-alpha.0)
• premajor: 预发布主版本 (1.0.0 → 2.0.0-alpha.0)

错误处理:

• 自动检查所有前置条件
• 发布失败时提供回滚选项
• 清晰的错误信息和解决建议
• 网络问题和权限问题的处理指导

注意事项:

• 确保已登录 cnpm 账户 (cnpm login) 或 npm 账户 (npm login)
• 确保具有包的发布权限
• Git 工作目录必须是干净状态
• 建议在发布前运行测试
• 遵循语义化版本控制 (SemVer) 规范

实现流程:

步骤 1: 环境检查

# 检查 package.json 存在
if [ ! -f "package.json" ]; thenecho "错误: 当前目录不是 Node.js 项目 (未找到 package.json)"exit 1
fi# 检查 git 状态
if ! git diff --quiet || ! git diff --staged --quiet; thenecho "错误: Git 工作目录不干净，请先提交或暂存所有更改"git status --porcelainexit 1
fi# 检查 cnpm 可用性（优先使用 cnpm）
if command -v cnpm &> /dev/null; thenPUBLISH_CMD="cnpm"echo "检测到 cnpm，将使用 cnpm 进行发布"
elsePUBLISH_CMD="npm"echo "未找到 cnpm，回退使用 npm 进行发布"
fi# 检查登录状态
if [ "$PUBLISH_CMD" = "cnpm" ]; then# 检查 cnpm 登录状态if ! cnpm whoami &> /dev/null; thenecho "错误: 未登录 cnpm，请运行 'cnpm login'"exit 1fi
else# 检查 npm 登录状态if ! npm whoami &> /dev/null; thenecho "错误: 未登录 npm，请运行 'npm login'"exit 1fi
fi

步骤 2: 版本选择交互

# 获取当前版本
CURRENT_VERSION=$(node -p "require('./package.json').version")
echo "当前版本: $CURRENT_VERSION"# 如果没有提供参数，显示交互菜单
if [ $# -eq 0 ]; thenecho "请选择版本类型:"echo "1) patch   (补丁版本 - bug 修复)"echo "2) minor   (小版本 - 新功能)"echo "3) major   (主版本 - 破坏性更改)"echo "4) prerelease (预发布版本)"echo "5) prepatch   (预发布补丁)"echo "6) preminor   (预发布小版本)"echo "7) premajor   (预发布主版本)"read -p "选择 [1-7]: " choicecase $choice in1) VERSION_TYPE="patch";;2) VERSION_TYPE="minor";;3) VERSION_TYPE="major";;4) VERSION_TYPE="prerelease";;5) VERSION_TYPE="prepatch";;6) VERSION_TYPE="preminor";;7) VERSION_TYPE="premajor";;*) echo "无效选择"; exit 1;;esac# 如果是预发布版本，询问标识符if [[ "$VERSION_TYPE" == "pre"* ]]; thenecho "请选择预发布标识符:"echo "1) alpha"echo "2) beta" echo "3) rc"read -p "选择 [1-3]: " pre_choicecase $pre_choice in1) PRERELEASE_ID="alpha";;2) PRERELEASE_ID="beta";;3) PRERELEASE_ID="rc";;*) echo "无效选择"; exit 1;;esacfi
elseVERSION_TYPE="$1"PRERELEASE_ID="$2"
fi

步骤 3: 构建检查和执行

# 检查 package.json 中的构建脚本
BUILD_SCRIPTS=("build" "compile" "dist" "prepare")
BUILD_CMD=""for script in "${BUILD_SCRIPTS[@]}"; doif npm run $script --dry-run &>/dev/null; thenBUILD_CMD=$scriptbreakfi
doneif [ -n "$BUILD_CMD" ]; thenecho "找到构建脚本: $BUILD_CMD"read -p "是否执行构建? [y/N]: " -n 1 -rechoif [[ $REPLY =~ ^[Yy]$ ]]; thenecho "执行构建中..."npm run $BUILD_CMD || { echo "构建失败"; exit 1; }echo "构建完成"fi
elseecho "未找到构建脚本，跳过构建步骤"
fi

步骤 4: 版本更新确认

# 预览新版本号
if [ -n "$PRERELEASE_ID" ]; thenNEW_VERSION=$(npm version $VERSION_TYPE --preid=$PRERELEASE_ID --no-git-tag-version --dry-run)
elseNEW_VERSION=$(npm version $VERSION_TYPE --no-git-tag-version --dry-run)
fiecho "版本更新预览:"
echo "  当前版本: $CURRENT_VERSION"
echo "  新版本:   $NEW_VERSION"read -p "确认版本更新? [y/N]: " -n 1 -r
echo
if [[ ! $REPLY =~ ^[Yy]$ ]]; thenecho "取消发布"exit 0
fi

步骤 5: 执行版本更新

# 更新版本号并创建 git 标签
if [ -n "$PRERELEASE_ID" ]; thennpm version $VERSION_TYPE --preid=$PRERELEASE_ID -m "chore: 发布版本 %s"
elsenpm version $VERSION_TYPE -m "chore: 发布版本 %s"
fiNEW_VERSION=$(node -p "require('./package.json').version")
echo "版本已更新为: $NEW_VERSION"

步骤 6: 变更日志管理

RELEASE_DATE=$(date +"%Y-%m-%d")if [ -f "CHANGELOG.md" ]; thenecho "更新现有 CHANGELOG.md..."# 备份原文件cp CHANGELOG.md CHANGELOG.md.bak# 在第一行后插入新版本信息{echo "# 更新日志"echo ""echo "## [$NEW_VERSION] - $RELEASE_DATE"echo ""echo "### 更新内容"echo "- 版本发布: $NEW_VERSION"echo ""tail -n +3 CHANGELOG.md.bak} > CHANGELOG.mdrm CHANGELOG.md.bakecho "CHANGELOG.md 已更新"
elseecho "未找到 CHANGELOG.md，自动创建..."# 创建标准格式的变更日志文件cat > CHANGELOG.md <<EOF
# 更新日志所有重要的项目更改都将记录在此文件中。此格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/) 标准，
并且本项目遵循 [语义化版本控制](https://semver.org/lang/zh-CN/)。## [$NEW_VERSION] - $RELEASE_DATE### 新增
- 项目初始版本发布### 更新内容
- 版本发布: $NEW_VERSION
EOFecho "CHANGELOG.md 已创建"
fi# 添加到 git 暂存区并修改最近一次提交
git add CHANGELOG.md
git commit --amend --no-edit
echo "变更日志已同步到版本提交"

步骤 7: 包发布

echo "开始发布包..."# 确定发布标签
PUBLISH_TAG=""
if [[ "$NEW_VERSION" == *"-alpha"* ]]; thenPUBLISH_TAG="--tag alpha"echo "检测到 alpha 版本，将发布到 alpha 标签"
elif [[ "$NEW_VERSION" == *"-beta"* ]]; thenPUBLISH_TAG="--tag beta"echo "检测到 beta 版本，将发布到 beta 标签"
elif [[ "$NEW_VERSION" == *"-rc"* ]]; thenPUBLISH_TAG="--tag rc"echo "检测到 rc 版本，将发布到 rc 标签"
elif [[ "$NEW_VERSION" == *"-"* ]]; thenPUBLISH_TAG="--tag next"echo "检测到预发布版本，将发布到 next 标签"
elseecho "检测到正式版本，将发布到 latest 标签（默认）"
firead -p "确认发布到 npm 仓库 (使用 $PUBLISH_CMD $PUBLISH_TAG)? [y/N]: " -n 1 -r
echo
if [[ ! $REPLY =~ ^[Yy]$ ]]; thenecho "取消发布"exit 0
fi# 执行发布
if $PUBLISH_CMD publish $PUBLISH_TAG; thenecho "包发布成功: $NEW_VERSION"if [ -n "$PUBLISH_TAG" ]; thenTAG_NAME=$(echo $PUBLISH_TAG | cut -d' ' -f2)echo "安装命令: npm install $(node -p "require('./package.json').name")@$TAG_NAME"fi
elseecho "发布失败，请检查网络连接和权限"read -p "是否回滚版本更改? [y/N]: " -n 1 -rechoif [[ $REPLY =~ ^[Yy]$ ]]; thengit reset --hard HEAD~1git tag -d "v$NEW_VERSION" 2>/dev/null || trueecho "版本更改已回滚"fiexit 1
fi

步骤 8: Git 同步

echo "推送到远程仓库..."
if git push && git push --tags; thenecho "Git 同步完成"
elseecho "Git 推送失败，但包已发布成功"echo "请手动推送: git push && git push --tags"
fiecho ""
echo "🎉 发布完成!"
echo "版本: $NEW_VERSION"
echo "命令: npm install $(node -p "require('./package.json').name")@$NEW_VERSION"

安全性:

• 发布前进行多重确认
• 不会发布包含敏感信息的代码
• 自动检查 .gitignore 和 .npmignore 配置
• 支持发布前钩子脚本执行
• 提供回滚机制处理发布失败