Back to Details

npm-publisher

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

NPM Publisher

NPM 发布器

Overview

概述

This skill provides a complete workflow for publishing npm packages with automated CI/CD. It handles version bumping, git tagging, and triggering automated npm publishing through GitHub Actions.
此技能提供了一套结合自动化CI/CD的完整npm包发布工作流，涵盖版本升级、Git打标签以及通过GitHub Actions触发自动化npm发布等操作。

Release Workflow

发布工作流

Follow this workflow when releasing a new version with unstaged changes:
当存在未暂存变更且需要发布新版本时，请遵循以下工作流：

Step 1: Stage All Changes

步骤1：暂存所有变更

Stage all pending changes:
bash
git add .
暂存所有待处理的变更：
bash
git add .

Step 2: Commit the Changes

步骤2：提交变更

Commit with a meaningful message describing what changed:
bash
git commit -m "$(cat <<'EOF'
<Description of changes>

<Optional: more details>
EOF
)"
Important: Never add attributions to a coding agent in commit messages.
使用有意义的提交信息描述变更内容：
bash
git commit -m "$(cat <<'EOF'
<变更描述>

<可选：更多细节>
EOF
)"
重要提示： 切勿在提交信息中添加代码Agent的署名。

Step 3: Determine Version Type

步骤3：确定版本类型

Ask the user which type of version bump is appropriate, or infer from the changes:
  • patch - Bug fixes (3.0.2 → 3.0.3)
  • minor - New features (3.0.3 → 3.1.0)
  • major - Breaking changes (3.1.0 → 4.0.0)
If unclear, analyze the git diff to determine the appropriate version type based on:
  • Bug fixes only → patch
  • New features without breaking changes → minor
  • Breaking changes or major refactors → major
询问用户适合的版本升级类型，或根据变更内容推断：
  • patch - 修复Bug（3.0.2 → 3.0.3）
  • minor - 新增功能（3.0.3 → 3.1.0）
  • major - 破坏性变更（3.1.0 → 4.0.0）
若不确定，可分析git diff结果来确定合适的版本类型：
  • 仅修复Bug → patch版本
  • 新增功能且无破坏性变更 → minor版本
  • 存在破坏性变更或重大重构 → major版本

Step 4: Bump Version

步骤4：升级版本

Bump the version using npm:
bash
npm version <patch|minor|major>
This command will:
  • Increment the version in package.json
  • Create a git commit with the version bump
  • Create a git tag (e.g., v3.0.3)
使用npm命令升级版本：
bash
npm version <patch|minor|major>
此命令将：
  • 更新package.json中的版本号
  • 创建包含版本升级的Git提交
  • 创建Git标签（例如：v3.0.3）

Step 5: Push Commits and Tags

步骤5：推送提交与标签

Push both commits and tags to the remote repository:
bash
git push && git push --tags
将提交和标签推送到远程仓库：
bash
git push && git push --tags

Step 6: Verify Publishing

步骤6：验证发布状态

After pushing, publishing happens automatically through CI/CD:
  1. GitHub Actions automatically publishes to npm when a new tag is pushed
  2. Wait approximately 30 seconds for CI to complete
  3. Verify the release succeeded:
bash
gh run list --limit 1
推送完成后，CI/CD将自动执行发布：
  1. 当新标签被推送时，GitHub Actions会自动将包发布到npm
  2. 等待约30秒，待CI流程完成
  3. 验证发布是否成功：
bash
gh run list --limit 1

Step 7: Test the New Version

步骤7：测试新版本

After CI completes successfully, verify the published version:
bash
undefined
CI流程成功完成后，验证已发布的版本：
bash
undefined

Clear npx cache if needed

如有需要，清空npx缓存

npx clear-npx-cache
npx clear-npx-cache

Test the new version (replace 'universal-skills' with the actual package name)

测试新版本（将'universal-skills'替换为实际包名）

npx <package-name> --version
undefined
npx <package-name> --version
undefined

Error Handling

错误处理

Common Issues

常见问题

Uncommitted changes error:
  • Ensure all changes are committed before running 
    npm version
  • Use 
    git status
    to check for uncommitted changes
Push rejected:
  • Pull latest changes with 
    git pull --rebase
  • Resolve any conflicts
  • Retry the push
CI/CD failure:
  • Check GitHub Actions logs: 
    gh run view --log
  • Common causes: failing tests, missing credentials, npm registry issues
  • Fix the issue and create a new patch release if needed
Version already exists:
  • Check if the version was already published: 
    npm view <package-name> versions
  • Bump to the next version if needed
未提交变更错误：
  • 确保在运行
    npm version
    前已提交所有变更
  • 使用
    git status
    检查是否存在未提交的变更
推送被拒绝：
  • 使用
    git pull --rebase
    拉取最新变更
  • 解决任何冲突
  • 重新尝试推送
CI/CD执行失败：
  • 查看GitHub Actions日志：
    gh run view --log
  • 常见原因：测试失败、凭据缺失、npm registry问题
  • 修复问题后，如有需要可创建新的patch版本发布
版本已存在：
  • 检查该版本是否已发布：
    npm view <package-name> versions
  • 如有需要，升级到下一个版本

Best Practices

最佳实践

  1. Always review changes before publishing with 
    git status
    and 
    git diff
  2. Run tests before publishing to catch issues early
  3. Write meaningful commit messages that explain the "why" not just the "what"
  4. Use semantic versioning consistently to manage user expectations
  5. Verify the release by testing the published package
  1. 发布前务必检查变更：使用
    git status
    和
    git diff
    查看变更内容
  2. 发布前运行测试：提前发现潜在问题
  3. 撰写有意义的提交信息：解释变更的“原因”而非仅说明“内容”
  4. 持续使用语义化版本：稳定用户预期
  5. 验证发布结果：测试已发布的包

Pre-Release Checklist

发布前检查清单

Before starting the release workflow, ensure:
  • All tests pass
  • Build succeeds without errors
  • Breaking changes are documented
  • Dependencies are up to date
  • No sensitive information in commits
开始发布工作流前，请确保：
  • 所有测试通过
  • 构建过程无错误
  • 破坏性变更已完成文档记录
  • 依赖项已更新至最新版本
  • 提交内容中无敏感信息