illegalCreed

中文

English

中文

English

Appearance

参考：semantic-release 速查 ​

基于 semantic-release v25 · 核于 2026-07

速查 ​

  • 心智模型：下一版本 = f(上次 tag, 之后的提交)；全自动、只在 CI 跑、无相关提交则不发。
  • 版本映射：fix/perf→patch、feat→minor、BREAKING CHANGE(或 !)→major、其余类型不发。
  • 生命周期九步：verifyConditions→analyzeCommits→verifyRelease→generateNotes→prepare→publish→addChannel→success→fail；仅 analyzeCommits 必需。
  • 默认插件：commit-analyzer+release-notes-generator+npm+github；自定义 plugins 是覆盖非追加。
  • 全局选项八个：extends/branches/repositoryUrl/tagFormat/plugins/dryRun/ci/debug。
  • CI 三前提：fetch-depth: 0、写权限、注入 token。
  • 凭据：GITHUB_TOKEN/NPM_TOKEN；GITHUB_TOKEN 兼 Git 推送 + API。
  • 分支三类：正式 / 维护(1.x) / 预发布(beta)；channel = npm dist-tag。
  • @semantic-release/git 回提交：默认信息带 [skip ci] 防死循环；多半不需要它。
  • 规范守门：commitlint + Husky 拦不合规提交（semantic-release 自己不校验）。
  • 运行：npx semantic-release@25；本地默认 dry-run；Node ≥ 22.14。

一、全局配置项 ​

选项默认值CLI说明
extends—-e/--extends继承 shareable config
branches['+([0-9])?(.{+([0-9]),x}).x','master','main','next','next-major',{name:'beta',prerelease:true},{name:'alpha',prerelease:true}]--branches发布分支定义
repositoryUrl由 pkg/git 推断-r/--repository-url仓库地址
tagFormatv${version}-t/--tag-formattag 命名模板
pluginscommit-analyzer,release-notes-generator,npm,github-p/--plugins插件列表（覆盖非追加）
dryRunCI:false 本地:true-d/--dry-run只演练不发布
citrue--ci/--no-ci是否要求 CI 环境
debugfalse--debug详细日志

插件选项不能用 CLI 传，只能写配置文件。优先级：CLI > 配置文件 > extends。

二、配置文件格式 ​

.releaserc（YAML/JSON）· .releaserc.{yaml,yml,json,js,cjs,mjs} · release.config.{js,cjs,mjs} · package.json 的 "release" 键。任选其一放仓库根。

三、提交类型 → 版本跳变（angular 预设） ​

提交跳变
fix: / perf:patch
feat:minor
feat!: / 脚注 BREAKING CHANGE:major
docs/style/chore/refactor/test/ci/build不发布

一次发布取区间内最高等级；可用 commit-analyzer 的 preset/releaseRules 定制。

四、生命周期与插件对照 ​

Step必需典型插件
verifyConditions否npm / github / git / changelog
analyzeCommits是commit-analyzer
verifyRelease否exec
generateNotes否release-notes-generator
prepare否changelog / npm / git
publish否npm / github / gitlab
addChannel否npm / github
success否github
fail否github

多插件同 step 合并：analyzeCommits 取最高；generateNotes 拼接；其余按 plugins 顺序依次执行。

五、常用插件 ​

插件step用途
@semantic-release/commit-analyzeranalyzeCommits判定发布类型
@semantic-release/release-notes-generatorgenerateNotes生成发布说明
@semantic-release/changelogverifyConditions/prepare写 CHANGELOG.md
@semantic-release/npmverifyConditions/prepare/publish改版本 + 发 npm
@semantic-release/gitverifyConditions/prepare回提交（默认带 [skip ci]）
@semantic-release/githubverifyConditions/publish/success/fail建 GitHub Release + 通知
@semantic-release/gitlabverifyConditions/publish建 GitLab Release
@semantic-release/exec几乎所有 step执行自定义命令（monorepo/非 JS）

六、分支属性 ​

属性适用含义
name全部（必填）分支名 / glob
channel全部npm dist-tag（首个正式分支默认 latest）
range维护版本范围（1.x，N.x/N.N.x 可省）
prerelease预发布标识（beta → 2.0.0-beta.1）

七、凭据速查 ​

变量用途
GITHUB_TOKEN / GH_TOKENGit 推送 + GitHub API（打 tag/建 Release/评论）
GITLAB_TOKEN / GL_TOKENGit 推送 + GitLab API
BB_TOKEN / GIT_CREDENTIALSBitbucket / 通用 Git 凭据
NPM_TOKENnpm publish（仅支持 auth-only 2FA；CI 用 automation token 或 OIDC）

八、常见坑清单 ​

  • fetch-depth: 0 忘配 → 浅克隆算不出历史 tag，误判首发 / 版本错乱。
  • plugins 覆盖非追加 → 自定义后漏列 commit-analyzer，永远不发版。
  • GitHub Actions 权限不足 → 未设 permissions: contents: write，打 tag/建 Release 报 403。
  • 分支保护挡推送 → 目标分支要求 PR，直接 push tag/commit 被拒；需允许发布身份绕过。
  • @semantic-release/git 少了 [skip ci] → 回提交再触发 CI，无谓构建甚至死循环。
  • 中途改 tagFormat → 匹配不到旧 tag，误判首发。
  • 在矩阵/多 Job 里跑多份 → 应仅在测试全过后的单个发布 Job 跑一次。
  • 提交不规范却没守门 → 该发的没发 / 版本乱跳；配 commitlint + Husky。
  • npm publish 级 2FA → CI 无法自动发布；改 automation token 或 OIDC Trusted Publishing。
  • 误以为「没发版」是 bug → 无相关提交时不发布是设计，退出码 0。

九、权威链接 ​