如何把 Node 包发布到 npm 仓库（以 telegraph-image-mcp 为例）

本文以实际项目 telegraph-image-mcp 为例，记录如何把 Node.js 包发布到 npm 官方仓库，供自己以后复用。

示例项目

telegraph-image-mcp 是一个 MCP Server，用于把图片/视频上传到 Telegraph-Image 图床，让 Cursor、Claude Desktop 等 AI 助手直接调用。

用户侧一行命令即可使用：

npx telegraph-image-mcp

前置准备

1. npm 账号

在 npmjs.com 注册账号，并记住：

• 用户名
• 邮箱
• 管理后台：https://www.npmjs.com/settings/你的用户名
• Token 管理：https://www.npmjs.com/settings/你的用户名/tokens

2. 创建 Granular Access Token（发布用）

npm 现在推荐用 Granular Access Token，不要用账号密码直接发布。

创建步骤：

1. 打开 Token 管理页 → Generate New Token → 选择 Granular Access Token
2. Token name：例如 telegraph-image-mcp-publish
3. Packages：勾选目标包名（如 telegraph-image-mcp）→ 权限选 Read and Write
4. 必须勾选 Bypass two-factor authentication（不勾会 403 Forbidden）
5. Organizations：个人账号不选
6. IP ranges：不填
7. 生成后立即复制保存，Token 只显示一次

注意：带写权限的 Granular Token 默认约 7 天过期，过期后需重新生成。

发布前检查

进入项目目录后，先确认构建和打包内容无误：

cd your-project

npm run build
npm pack --dry-run    # 预览将要上传的文件

确认 package.json 里的 name、version、files 字段正确。

方式一：用 Token 发布（推荐）

适合 CI/CD 或一次性本地发布，用完即删，不把 Token 长期留在机器上。

cd your-project

# 临时写入 token（发布完务必删除 .npmrc）
echo "//registry.npmjs.org/:_authToken=你的Token" > .npmrc

npm publish

# 验证是否发布成功
npm view telegraph-image-mcp version

# 清理 token 文件
rm .npmrc

也可以用环境变量，避免写入文件：

NPM_CONFIG_//registry.npmjs.org/:_authToken=你的Token npm publish

方式二：npm login 后发布

适合本机长期开发、偶尔手动发布。

npm login
# Username: 你的用户名
# Password: 粘贴 Granular Token（不是 npm 登录密码！）
# Email: 你的邮箱

npm publish

关键点：npm login 时 Password 填的是 Granular Token，不是网页登录密码。

更新版本再发布

# patch: 0.1.0 → 0.1.1
# minor: 0.1.0 → 0.2.0
# major: 0.1.0 → 1.0.0
npm version patch

npm publish

# 同步推送到 GitHub
git push && git push --tags

完整发版流程（GitHub + npm）

日常发版可以按这个顺序走：

cd your-project

# 1. 改代码并构建
npm run build

# 2. 提交 Git
git add .
git commit -m "feat: xxx"
git push

# 3. 升版本 + 发 npm
npm version patch
echo "//registry.npmjs.org/:_authToken=你的Token" > .npmrc
npm publish
rm .npmrc

# 4. 推 tag
git push --tags

常见问题

发布报 403 Forbidden

最常见原因：Granular Token 没有勾选 Bypass two-factor authentication。重新生成 Token 并勾选该项。

Token 过期

写权限 Granular Token 默认有效期较短（约 7 天），过期后到 npm 后台重新生成。

包名已被占用

package.json 里的 name 在 npm 上必须唯一。可以改用 scoped 包名，例如 @gwozai/telegraph-image-mcp。

发布记录（telegraph-image-mcp）

相关阅读

• npm设置代理 windows 所有的东西都可以下载 — 如果 npm install / npm publish 网络不通，先配代理
• Telegraph-Image 图床 MCP 使用指南（Cursor） — 用户侧如何接入 MCP