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" ]; then
    echo "错误: 当前目录不是 Node.js 项目 (未找到 package.json)"
    exit 1
fi

# 检查 git 状态
if ! git diff --quiet || ! git diff --staged --quiet; then
    echo "错误: Git 工作目录不干净，请先提交或暂存所有更改"
    git status --porcelain
    exit 1
fi

# 检查 cnpm 可用性（优先使用 cnpm）
if command -v cnpm &> /dev/null; then
    PUBLISH_CMD="cnpm"
    echo "检测到 cnpm，将使用 cnpm 进行发布"
else
    PUBLISH_CMD="npm"
    echo "未找到 cnpm，回退使用 npm 进行发布"
fi

# 检查登录状态
if [ "$PUBLISH_CMD" = "cnpm" ]; then
    # 检查 cnpm 登录状态
    if ! cnpm whoami &> /dev/null; then
        echo "错误: 未登录 cnpm，请运行 'cnpm login'"
        exit 1
    fi
else
    # 检查 npm 登录状态
    if ! npm whoami &> /dev/null; then
        echo "错误: 未登录 npm，请运行 'npm login'"
        exit 1
    fi
fi

步骤 2: 版本选择交互

# 获取当前版本
CURRENT_VERSION=$(node -p "require('./package.json').version")
echo "当前版本: $CURRENT_VERSION"

# 如果没有提供参数，显示交互菜单
if [ $# -eq 0 ]; then
    echo "请选择版本类型:"
    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]: " choice
    
    case $choice in
        1) 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"* ]]; then
        echo "请选择预发布标识符:"
        echo "1) alpha"
        echo "2) beta" 
        echo "3) rc"
        read -p "选择 [1-3]: " pre_choice
        
        case $pre_choice in
            1) PRERELEASE_ID="alpha";;
            2) PRERELEASE_ID="beta";;
            3) PRERELEASE_ID="rc";;
            *) echo "无效选择"; exit 1;;
        esac
    fi
else
    VERSION_TYPE="$1"
    PRERELEASE_ID="$2"
fi

步骤 3: 构建检查和执行

# 检查 package.json 中的构建脚本
BUILD_SCRIPTS=("build" "compile" "dist" "prepare")
BUILD_CMD=""

for script in "${BUILD_SCRIPTS[@]}"; do
    if npm run $script --dry-run &>/dev/null; then
        BUILD_CMD=$script
        break
    fi
done

if [ -n "$BUILD_CMD" ]; then
    echo "找到构建脚本: $BUILD_CMD"
    read -p "是否执行构建? [y/N]: " -n 1 -r
    echo
    if [[ $REPLY =~ ^[Yy]$ ]]; then
        echo "执行构建中..."
        npm run $BUILD_CMD || { echo "构建失败"; exit 1; }
        echo "构建完成"
    fi
else
    echo "未找到构建脚本，跳过构建步骤"
fi

步骤 4: 版本更新确认

# 预览新版本号
if [ -n "$PRERELEASE_ID" ]; then
    NEW_VERSION=$(npm version $VERSION_TYPE --preid=$PRERELEASE_ID --no-git-tag-version --dry-run)
else
    NEW_VERSION=$(npm version $VERSION_TYPE --no-git-tag-version --dry-run)
fi

echo "版本更新预览:"
echo "  当前版本: $CURRENT_VERSION"
echo "  新版本:   $NEW_VERSION"

read -p "确认版本更新? [y/N]: " -n 1 -r
echo
if [[ ! $REPLY =~ ^[Yy]$ ]]; then
    echo "取消发布"
    exit 0
fi

步骤 5: 执行版本更新

# 更新版本号并创建 git 标签
if [ -n "$PRERELEASE_ID" ]; then
    npm version $VERSION_TYPE --preid=$PRERELEASE_ID -m "chore: 发布版本 %s"
else
    npm version $VERSION_TYPE -m "chore: 发布版本 %s"
fi

NEW_VERSION=$(node -p "require('./package.json').version")
echo "版本已更新为: $NEW_VERSION"

步骤 6: 变更日志管理

RELEASE_DATE=$(date +"%Y-%m-%d")

if [ -f "CHANGELOG.md" ]; then
    echo "更新现有 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.md
    
    rm CHANGELOG.md.bak
    echo "CHANGELOG.md 已更新"
else
    echo "未找到 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
EOF
    echo "CHANGELOG.md 已创建"
fi

# 添加到 git 暂存区并修改最近一次提交
git add CHANGELOG.md
git commit --amend --no-edit
echo "变更日志已同步到版本提交"

步骤 7: 包发布

echo "开始发布包..."

# 确定发布标签
PUBLISH_TAG=""
if [[ "$NEW_VERSION" == *"-alpha"* ]]; then
    PUBLISH_TAG="--tag alpha"
    echo "检测到 alpha 版本，将发布到 alpha 标签"
elif [[ "$NEW_VERSION" == *"-beta"* ]]; then
    PUBLISH_TAG="--tag beta"
    echo "检测到 beta 版本，将发布到 beta 标签"
elif [[ "$NEW_VERSION" == *"-rc"* ]]; then
    PUBLISH_TAG="--tag rc"
    echo "检测到 rc 版本，将发布到 rc 标签"
elif [[ "$NEW_VERSION" == *"-"* ]]; then
    PUBLISH_TAG="--tag next"
    echo "检测到预发布版本，将发布到 next 标签"
else
    echo "检测到正式版本，将发布到 latest 标签（默认）"
fi

read -p "确认发布到 npm 仓库 (使用 $PUBLISH_CMD $PUBLISH_TAG)? [y/N]: " -n 1 -r
echo
if [[ ! $REPLY =~ ^[Yy]$ ]]; then
    echo "取消发布"
    exit 0
fi

# 执行发布
if $PUBLISH_CMD publish $PUBLISH_TAG; then
    echo "包发布成功: $NEW_VERSION"
    if [ -n "$PUBLISH_TAG" ]; then
        TAG_NAME=$(echo $PUBLISH_TAG | cut -d' ' -f2)
        echo "安装命令: npm install $(node -p "require('./package.json').name")@$TAG_NAME"
    fi
else
    echo "发布失败，请检查网络连接和权限"
    read -p "是否回滚版本更改? [y/N]: " -n 1 -r
    echo
    if [[ $REPLY =~ ^[Yy]$ ]]; then
        git reset --hard HEAD~1
        git tag -d "v$NEW_VERSION" 2>/dev/null || true
        echo "版本更改已回滚"
    fi
    exit 1
fi

步骤 8: Git 同步

echo "推送到远程仓库..."
if git push && git push --tags; then
    echo "Git 同步完成"
else
    echo "Git 推送失败，但包已发布成功"
    echo "请手动推送: git push && git push --tags"
fi

echo ""
echo "🎉 发布完成!"
echo "版本: $NEW_VERSION"
echo "命令: npm install $(node -p "require('./package.json').name")@$NEW_VERSION"

安全性:

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