企业官网建设流程全解析

刚刚执行npm publish却看到 "Two-factor authentication
or granular access token with bypass 2fa enabled is required" 的红色报错？别担心，5分钟内让你恢复发布能力。

快速诊断：为什么突然不能发布了？

如果你最近两天突然遇到这个报错，根本原因是：npm 在2025年12月9日永久撤销了所有“经典令牌”。

以前能用的令牌现在全部失效，必须使用新的
自动化令牌或
粒度访问令牌来发布包。

🚀 5分钟紧急解决方案

方案A：个人开发者快速恢复发布（推荐）

如果你在个人电脑上发布自己的包，这是最快的方法：

1.创建自动化令牌

# 登录 npm 网站，进入令牌管理 # 访问：https://www.npmjs.com/settings/你的用户名/tokens # 或使用 CLI（需要 npm v10+） npm token create --type automation --read-only false

1. 复制生成的令牌字符串（形如npm_xxxxxx）
2. 配置到本地环境

# 一次性使用（仅本次终端会话有效） npm config set //registry.npmjs.org/:_authToken=你的令牌字符串 # 或永久保存到项目（推荐） echo "//registry.npmjs.org/:_authToken=你的令牌字符串" >> .npmrc

4.立即测试发布

npm publish --dry-run # 先试运行 npm publish # 实际发布

方案B：团队项目配置（包管理员操作）

如果你管理一个团队包，需要为成员配置权限：

创建粒度访问令牌

• 访问 npm 网站令牌页面
• 点击"Generate New Token"→ 选择"Granular Access Token"
• 配置权限时必须勾选："Bypass 2FA"

分配精确权限

# 示例：创建仅能发布特定包的令牌 npm token create --granular \ --package "团队包名" \ --permissions publish \ --bypass-2fa \ --expiry 30d # 30天有效期

1. 安全分享给团队成员

• 通过密码管理器分享
• 或配置到团队 CI/CD 环境变量

方案C：GitHub Actions
自动发布修复

如果你的 CI/CD 突然失败，更新工作流配置：

# .github/workflows/publish.yml name: Publish to npm on: push: branches: [main] jobs: publish: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: '20' registry-url: 'https://registry.npmjs.org/' - run: npm ci - name: Publish Package run: npm publish env: # 关键：使用新的自动化令牌 NODE_AUTH_TOKEN: ${{ secrets.NPM_AUTOMATION_TOKEN }}

在 GitHub 仓库设置中：

1. 进入 Settings → Secrets and variables → Actions
2. 更新NPM_AUTOMATION_TOKEN值为新创建的自动化令牌

🔍 故障排查对照表

快速检查命令：

# 1. 检查当前认证状态 npm whoami # 2. 验证令牌权限 npm access ls-collaborators 你的包名 # 3. 检查本地配置 npm config get //registry.npmjs.org/:_authToken # 4. 查看令牌类型（前4字符） # npm_ = 自动化/粒度令牌 | npm_org = 组织令牌 | 其他 = 已失效

📚 理解新令牌体系（原理简介）

为什么必须改变？

旧的“经典令牌”一旦泄露就永久有效，安全隐患极大。新的令牌体系提供：

1. 自动化令牌：CI/CD 专用，自动绕过 2FA，最长 90 天
2. 粒度访问令牌：精细权限控制，可选 bypass-2fa
3. 会话令牌：npm login生成，仅 2 小时有效

令牌类型对比

🛡️ 长期最佳实践

1. 令牌安全管理

# 定期列出所有令牌 npm token list # 撤销不再需要的令牌 npm token revoke 令牌ID前10字符 # 设置日历提醒，每80天轮换令牌

2. 项目标准化配置

# 项目 .npmrc 示例 @scope:registry=https://registry.npmjs.org/ //registry.npmjs.org/:_authToken=${NPM_TOKEN} always-auth=true # .env 文件（不要提交到Git！） NPM_TOKEN=npm_你的自动化令牌

3. 探索未来方案：可信发布

对于开源项目，考虑迁移到更安全的可信发布：

• 完全无需长期令牌
• 通过 GitHub Actions
  OIDC 自动获取临时凭证
• npm 官方推荐的新标准

总结与下一步

立即行动清单：

1. ✅ 创建新的自动化令牌（个人）或粒度令牌（团队）
2. ✅ 更新本地.npmrc或 CI/CD 环境变量
3. ✅ 测试npm publish --dry-run
4. 🔄 设置令牌到期提醒（80天后）

长期策略：

• 个人项目：使用自动化令牌 + 定期轮换
• 团队项目：粒度访问令牌 + 权限审计
• 开源项目：探索可信发布（Trusted Publishing）

这次变更虽然带来了短期的适配成本，但显著提升了整个 npm 生态系统的安全性。正确配置后，你的发布流程将更加健壮和安全。