npm-publish

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

npm-publish

npm包发布

Publish npm packages using bun with proper versioning, changelog management, and git workflow.

使用Bun工具发布npm包，包含规范的版本管理、变更日志（changelog）管理及Git工作流。

Workflow

工作流程

1. Verify npm Login

1. 验证npm登录状态

First, check if the user is logged into npm:

bash

npm whoami

If this returns a username, proceed. If it errors with "not logged in", stop and instruct the user:

"You need to log into npm first. Please run
npm login
in your terminal and complete authentication, then let me know when you're ready."

Do not proceed with any publish steps until
npm whoami
succeeds. The user must handle npm login themselves as it requires interactive authentication.

首先，检查用户是否已登录npm：

bash

npm whoami

如果该命令返回用户名，则继续后续操作。若返回“not logged in”（未登录）错误，请停止操作并告知用户：

“你需要先登录npm。请在终端中运行
npm login
完成认证，准备好后告知我。”

**在

npm whoami

命令执行成功前，请勿进行任何发布步骤。**用户必须自行完成npm登录，因为该操作需要交互式认证。

2. Check Current State

2. 检查当前状态

Determine what needs to be released:

bash

undefined

确定需要发布的内容：

bash

undefined

Check last published version

查看最后发布的版本

npm view <package-name> version

Check local package.json version

查看本地package.json中的版本

cat package.json | grep '"version"'

Check commits since last release

查看上次发布后的提交记录

git log --oneline $(git describe --tags --abbrev=0 2>/dev/null || echo HEAD~10)..HEAD


If no tags exist, check git log for release commits to identify the last published state.

git log --oneline $(git describe --tags --abbrev=0 2>/dev/null || echo HEAD~10)..HEAD


如果没有标签记录，可查看Git提交日志中的发布相关提交，以此确定上次发布的状态。

3. Update Version

3. 更新版本

For projects in rapid/early development (0.x.x), always bump the patch version:

0.0.1 → 0.0.2 → 0.0.3 ...

Avoid major or minor bumps unless explicitly requested. Early-stage projects benefit from frequent small releases.

Edit

package.json

to update the version field.

对于处于快速/早期开发阶段的项目（版本号为0.x.x），始终更新补丁版本号：

0.0.1 → 0.0.2 → 0.0.3 ...

除非用户明确要求，否则请勿更新主版本号或次版本号。早期阶段的项目适合通过频繁的小版本发布迭代。

编辑

package.json

文件，更新version字段。

4. Update CHANGELOG.md

4. 更新CHANGELOG.md

Check if a changelog exists. If so, add an entry for the new version following the existing format. Typical structure:

markdown

undefined

检查是否存在变更日志文件。若存在，请按照现有格式为新版本添加条目。典型结构如下：

markdown

undefined

[X.X.X] - YYYY-MM-DD

Added

New features

新增功能

Changed

Changes to existing functionality

现有功能变更

Fixed

Bug fixes


Summarize the commits since the last release into appropriate categories.

Bug修复


将上次发布后的提交记录汇总到对应的分类中。

5. Build and Verify

5. 构建与验证

Run the project's build command to ensure everything compiles:

bash

bun run build

运行项目的构建命令，确保所有代码编译正常：

bash

bun run build

6. Commit and Push FIRST

6. 先提交并推送至Git

Critical: Always push to git before publishing to npm.

bash

git add package.json CHANGELOG.md
git commit -m "Release vX.X.X"
git push origin <branch>

This ensures the published code matches what's in the repository. Publishing before pushing creates version mismatches that require additional releases to fix.

关键步骤：在发布到npm之前，务必先推送代码至Git仓库。

bash

git add package.json CHANGELOG.md
git commit -m "Release vX.X.X"
git push origin <branch>

这能确保发布的代码与仓库中的代码保持一致。若先发布再推送，会导致版本不匹配，需要额外发布版本来修复问题。

7. Request OTP

7. 请求OTP验证码

Before attempting to publish, ask the user for their npm OTP (One-Time Password) code. This is standard practice for npm 2FA:

"Please provide your npm OTP code for publishing."

Wait for the user to provide the 6-digit code before proceeding.

在尝试发布前，向用户索要npm OTP（一次性密码）验证码。这是npm双因素认证的标准流程：

“请提供你的npm OTP验证码用于发布操作。”

等待用户提供6位验证码后，再继续后续操作。

8. Publish with bun

8. 使用Bun发布

Use

bun publish

with the OTP:

bash

bun publish --access public --otp <code>

For scoped packages (@org/package),

--access public

is required unless publishing to a private registry.

使用

bun publish

命令并传入OTP验证码：

bash

bun publish --access public --otp <code>

对于作用域包（@org/package），除非发布至私有仓库，否则必须添加

--access public

参数。

9. Verify Publication

9. 验证发布结果

After publishing, verify the new version is live:

bash

npm view <package-name> version

Note: The bun/npm registry may take up to 5 minutes to reflect the new version. Do not attempt to work around this delay by using npm directly or re-publishing. Simply wait and verify again if needed.

发布完成后，验证新版本是否已上线：

bash

npm view <package-name> version

**注意：**Bun/npm注册表可能需要最多5分钟的时间来同步新版本。请勿通过直接使用npm或重新发布的方式绕过此延迟，只需等待一段时间后再次验证即可。

Common Issues

常见问题

Version Already Published

版本已发布

If the version already exists on npm, bump to the next patch version and repeat the workflow.

若该版本已在npm上存在，请更新至下一个补丁版本，然后重复整个工作流程。

OTP Expired

OTP验证码过期

OTP codes are time-sensitive (usually 30 seconds). If publishing fails due to expired OTP, request a fresh code from the user.

OTP验证码具有时效性（通常为30秒）。若因验证码过期导致发布失败，请向用户索要新的验证码。

Registry Delay

注册表延迟

After successful publish,

npm view

may still show the old version for several minutes. This is normal behavior—do not re-publish or attempt workarounds.

发布成功后，

npm view

可能仍会在数分钟内显示旧版本。这是正常现象——请勿重新发布或尝试其他解决方法。