Back to Details

npm-publish

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

npm Publish Skill

npm 发布技能

Publish 
@autumnsgrove/groveengine
to npm while keeping the default registry as GitHub Packages.
将
@autumnsgrove/groveengine
发布至npm，同时保持默认仓库为GitHub Packages。

When to Activate

激活时机

Activate this skill when:
  • User says "publish to npm"
  • User says "release to npm"
  • User says "bump and publish"
  • User says "/npm-publish"
在以下场景激活此技能：
  • 用户说"发布到npm"
  • 用户说"发布版本到npm"
  • 用户说"升级版本并发布"
  • 用户说"/npm-publish"

The Workflow

工作流

CRITICAL: The package.json uses GitHub Packages by default. You MUST swap to npm, publish, then swap BACK.
1. Bump version in packages/engine/package.json
2. Swap publishConfig to npm registry
3. Build the package
4. Publish to npm
5. Swap publishConfig BACK to GitHub Packages
6. Commit the version bump
7. Push to remote
重要提示：package.json默认使用GitHub Packages。你必须切换到npm仓库，完成发布后，再切换回原仓库。
1. 升级packages/engine/package.json中的版本号
2. 将publishConfig切换为npm仓库
3. 构建包
4. 发布至npm
5. 将publishConfig切换回GitHub Packages
6. 提交版本升级的变更
7. 推送到远程仓库

Step-by-Step Execution

分步执行指南

Step 1: Bump Version

步骤1：升级版本号

Edit 
packages/engine/package.json
:
json
"version": "X.Y.Z",  // Increment appropriately
Use semantic versioning:
  • MAJOR (X): Breaking changes
  • MINOR (Y): New features, backwards compatible
  • PATCH (Z): Bug fixes, backwards compatible
编辑
packages/engine/package.json
：
json
"version": "X.Y.Z",  // 按需升级版本
使用语义化版本控制：
  • 主版本号（X）：不兼容的重大变更
  • 次版本号（Y）：新增功能，向后兼容
  • 修订版本号（Z）：修复bug，向后兼容

Step 2: Swap to npm Registry

步骤2：切换到npm仓库

BEFORE (GitHub Packages - default):
json
"publishConfig": {
  "registry": "https://npm.pkg.github.com"
},
AFTER (npm - for publishing):
json
"publishConfig": {
  "registry": "https://registry.npmjs.org",
  "access": "public"
},
切换前（默认使用GitHub Packages）：
json
"publishConfig": {
  "registry": "https://npm.pkg.github.com"
},
切换后（用于发布的npm仓库）：
json
"publishConfig": {
  "registry": "https://registry.npmjs.org",
  "access": "public"
},

Step 3: Build Package

步骤3：构建包

bash
cd /Users/autumn/Documents/Projects/GroveEngine/packages/engine
pnpm run package
bash
cd /Users/autumn/Documents/Projects/GroveEngine/packages/engine
pnpm run package

Step 4: Publish to npm

步骤4：发布至npm

bash
npm publish --access public
The 
prepublishOnly
script runs 
pnpm run package
automatically, so this may rebuild.
Verify success with:
+ @autumnsgrove/groveengine@X.Y.Z
bash
npm publish --access public
prepublishOnly
脚本会自动执行
pnpm run package
，因此这一步可能会重新构建包。
通过以下信息验证发布成功：
+ @autumnsgrove/groveengine@X.Y.Z

Step 5: Swap BACK to GitHub Packages

步骤5：切换回GitHub Packages

CRITICAL - DO NOT FORGET THIS STEP
Change 
packages/engine/package.json
back to:
json
"publishConfig": {
  "registry": "https://npm.pkg.github.com"
},
重要提示 - 请勿忘记此步骤
将
packages/engine/package.json
改回：
json
"publishConfig": {
  "registry": "https://npm.pkg.github.com"
},

Step 6: Commit Version Bump

步骤6：提交版本升级的变更

bash
cd /Users/autumn/Documents/Projects/GroveEngine
git add packages/engine/package.json
git commit -m "chore: bump version to X.Y.Z"
git push origin main
bash
cd /Users/autumn/Documents/Projects/GroveEngine
git add packages/engine/package.json
git commit -m "chore: bump version to X.Y.Z"
git push origin main

Quick Reference Commands

快速参考命令

bash
undefined
bash
undefined

From project root:

从项目根目录执行：

1. Edit version in packages/engine/package.json

1. 编辑packages/engine/package.json中的版本号

2. Edit publishConfig to npm registry

2. 将publishConfig切换为npm仓库

3. Build and publish

3. 构建并发布

cd packages/engine pnpm run package npm publish --access public
cd packages/engine pnpm run package npm publish --access public

4. Edit publishConfig back to GitHub

4. 将publishConfig切换回GitHub仓库

5. Commit and push (from project root)

5. 提交并推送（从项目根目录）

git add packages/engine/package.json git commit -m "chore: bump version to X.Y.Z" git push origin main
undefined
git add packages/engine/package.json git commit -m "chore: bump version to X.Y.Z" git push origin main
undefined

Verification

验证发布结果

After publishing, verify on npm:
bash
npm view @autumnsgrove/groveengine version
Or visit: https://www.npmjs.com/package/@autumnsgrove/groveengine
发布完成后，通过以下命令在npm上验证：
bash
npm view @autumnsgrove/groveengine version
或访问：https://www.npmjs.com/package/@autumnsgrove/groveengine

Troubleshooting

故障排除

OTP/2FA Error

OTP/双因素认证错误

npm error code EOTP
npm error This operation requires a one-time password
Solution: Create a granular access token with "Bypass 2FA" enabled:
  1. Go to https://www.npmjs.com/settings/autumnsgrove/tokens
  2. Generate New Token → Granular Access Token
  3. Enable "Bypass 2FA"
  4. Set token: 
    npm config set //registry.npmjs.org/:_authToken=npm_YOUR_TOKEN
See 
AgentUsage/npm_publish.md
for detailed token setup.
npm error code EOTP
npm error This operation requires a one-time password
解决方法：创建一个带有“绕过双因素认证”权限的精细化访问令牌：
  1. 访问https://www.npmjs.com/settings/autumnsgrove/tokens
  2. 生成新令牌 → 精细化访问令牌
  3. 启用“绕过双因素认证”
  4. 设置令牌：
    npm config set //registry.npmjs.org/:_authToken=npm_YOUR_TOKEN
详细的令牌设置步骤请查看
AgentUsage/npm_publish.md
。

Package Already Published

包已发布

npm error 403 - You cannot publish over the previously published versions
Solution: You forgot to bump the version. Increment it and try again.
npm error 403 - You cannot publish over the previously published versions
解决方法：你忘记升级版本号了。升级版本号后重试。

Wrong Registry in Commit

提交时仓库配置错误

If you accidentally committed with npm registry, fix it:
bash
undefined
如果你不小心提交了npm仓库的配置，修复方法：
bash
undefined

Edit publishConfig back to GitHub

将publishConfig切换回GitHub仓库

git add packages/engine/package.json git commit --amend --no-edit git push --force-with-lease origin main
undefined
git add packages/engine/package.json git commit --amend --no-edit git push --force-with-lease origin main
undefined

Registry Swap Reference

仓库配置切换参考

RegistrypublishConfig
GitHub (default)
"registry": "https://npm.pkg.github.com"
npm (for publish)
"registry": "https://registry.npmjs.org", "access": "public"
仓库publishConfig 配置
GitHub（默认）
"registry": "https://npm.pkg.github.com"
npm（用于发布）
"registry": "https://registry.npmjs.org", "access": "public"

Checklist

检查清单

Before starting:
  • Decided on new version number
  • All changes committed and pushed
During publish:
  • Version bumped in package.json
  • publishConfig swapped to npm
  • Package built successfully
  • Published to npm (see 
    + @autumnsgrove/groveengine@X.Y.Z
    )
  • publishConfig swapped BACK to GitHub
  • Version bump committed
  • Pushed to remote
开始发布前：
  • 确定新的版本号
  • 所有变更已提交并推送到远程仓库
发布过程中：
  • 已升级package.json中的版本号
  • 已将publishConfig切换为npm仓库
  • 包构建成功
  • 已发布至npm（看到
    + @autumnsgrove/groveengine@X.Y.Z
    提示）
  • 已将publishConfig切换回GitHub Packages
  • 已提交版本升级的变更
  • 已推送到远程仓库

Related

相关文档

  • AgentUsage/npm_publish.md
    - Token setup and 2FA workaround
  • packages/engine/package.json
    - Package configuration
  • AgentUsage/npm_publish.md
    - 令牌设置与双因素认证解决方案
  • packages/engine/package.json
    - 包配置文件