Next.js Issue Triage 机制详解：自动关闭、标签体系与最小复现要求

本文基于 Next.js 仓库的 Issue Triage 规范，系统讲解该仓库的 issue 分诊（triage）机制：哪些 bug 报告会被自动关闭、五类手动标签各自的含义与超时策略、已验证（verified）issue 如何追踪，以及关闭后如何申请重开。读完本文，你可以准确预判一个 issue 在 Next.js 仓库中的生命周期，并知道如何提交一份不会被自动关闭、能被维护者快速处理的 bug 报告。

分诊总览：维护者处理每一个 Issue 与 PR

Next.js 仓库的维护者会对打开的每一个 issue 和 PR 进行分诊（triage）。分诊分为两条路径：

• 自动分诊：由 GitHub Actions 工作流驱动，主要校验 bug 报告的复现链接有效性、自动补打受影响区域的标签；
• 手动分诊：维护者人工判定 issue 归属，打上带行动指引的标签，并附带一条解释“下一步该做什么”的自动评论。

文档中同时强调：功能请求（feature request）不应以 issue 形式提交，而应放到 Discussions 的 Ideas 分类中填写模板提交。这一点也在 bug 报告模板 的开头说明中被反复重申——功能请求和文档改进请求都应走 Discussions 渠道。

初始标签：三类基础分类

每个新打开的 issue 会带有一个基础分类标签，用于标识问题类型：

标签	含义
bug	Next.js 框架本身存在的问题
documentation	Next.js 文档的改进反馈或文档本身的问题
examples	examples 目录中某个示例项目的问题

其中 bug 标签是自动分诊的触发条件之一：仓库的分诊工作流配置了 reproduction-issue-labels: 'bug,'，即只有带 bug 标签的 issue 才会进入复现链接校验流程（见下文 triage.yml）。

Bug 报告的自动分诊

复现链接有效性校验

对于 bug 报告，如果复现（reproduction）缺失或不充分，issue 会被自动关闭，并附上一条给出正确行动路径的自动评论，该评论内容维护在 invalid-link.md。同时 issue 会被打上 invalid link 标签以便标识。

自动关闭的典型情形包括（引自 invalid-link.md）：

• 没有提供链接，或提供的链接无效（例如 "example.com"、"n/a"、"稍后补充"这类占位符）；
• 链接指向私有仓库——维护者不应被要求走一套冗长的企业代码 onboarding 流程才能验证问题；
• 链接存在但没填在模板指定的 "Link to the code that reproduces this issue" 栏位里。

从源码结构看，这套校验由 triage.yml 中运行的 balazsorban44/nissuer Action 完成，关键配置为：

• reproduction-hosts: 仅接受 github.com、bitbucket.org、gitlab.com、codesandbox.io、stackblitz.com 这几个托管域名；
• reproduction-blocklist: 排除 Next.js 仓库自身及其根目录（github.com/vercel/next.js.*、github.com/\w*/?$ 等）；
• reproduction-link-section: 用正则 ### Link to the code that reproduces this issue(.*)### To Reproduce 精确定位模板中"复现链接"栏位，链接必须出现在该栏位内才被认可；
• reproduction-invalid-label: 校验失败时自动打上的 invalid link 标签。

官方推荐的复现模板位于仓库内：

• App Router：examples/reproduction-template，可通过 npx create-next-app -e reproduction-template 创建；
• Pages Router：examples/reproduction-template-pages，可通过 npx create-next-app -e reproduction-template-pages 创建。

对于"仓库是私有的、无法公开"的常见疑虑，自动评论给出了明确建议：不要直接公开整个仓库，而是用上述模板新建一个仓库，只移入与问题相关的代码，并逐一移除无关的页面/API 路由、依赖、第三方服务、环境变量和私有包。

按受影响区域自动打标签

如果在 bug 报告模板中填写了 "Which area(s) are affected? (Select all that apply)" 多选栏位，分诊工作流会自动为 issue 打上对应的区域标签。从 triage.yml 的配置可见，nissuer 通过 label-area-section 正则截取该栏位内容，并按 label-area-match: 'name' 匹配选项名生成标签。模板中可选的区域涵盖 create-next-app、Image (next/image)、Middleware、Route Handlers、Server Actions、Turbopack、SWC、Webpack、Partial Prerendering (PPR) 等（完整清单见 1.bug_report.yml）。

手动分诊：五类标签及其后果

如果问题只与提问者自己的项目相关、而与 Next.js 本身无关，issue 会被转换为 Discussions 的 Help（求助）分类讨论。除此之外，维护者还会手动为 issue 打上以下五类标签，每个标签都会附带一条对应的自动评论。

1. please add a complete reproduction（补充完整复现）

含义：提供的复现信息不足以让维护者排查问题。若后续没有提供足够的复现，issue 将在 2 天无活动后自动关闭，自动评论内容维护在 invalid-reproduction.md。

该评论对"最小复现"给出了具体标准：复现应尽可能最小化，移除与问题无关的代码、文件与依赖；不依赖密钥、私有 registry、私有依赖或任何无法公开的数据；除非问题本身就与 monorepo 相关，否则避免整个 monorepo。同时要求先对照 next@canary 验证问题是否已修复。如果无法构造干净的复现，评论还给出替代贡献方式：在 releases 中定位引入该问题的首个 canary 版本（可用 npm install next@<version> 安装特定版本），帮助维护者缩小排查范围。

2. please verify canary（用 canary 验证）

含义：问题未在 next@canary 版本上验证。Next.js 的 canary 版本每天发布，包含所有尚未进入稳定版的功能与修复，可以把它看作一个公开 beta。由于不少问题可能已在 canary 中修复，维护者要求先验证问题是否仍然存在；未在 canary 上验证的 issue 将在 14 天无活动后自动关闭，自动评论内容维护在 verify-canary.md。

验证方式是在项目中运行 npm install next@canary，然后按自己的复现步骤测试。如果 canary 上无法复现，说明问题已修复，issue 可以关闭。评论还特别说明了一个常见疑问——"为什么 issue 开了很久现在才要求验证 canary"：Next.js 不会把 bug 修复回移（backport）到旧版本，而是尽量在主要版本之间只引入少量破坏性变更。

3. please simplify reproduction（简化复现）

含义：提供了复现，但过于复杂或步骤过多，维护者难以快速复现。若没有提供简化后的复现，issue 将在 14 天无活动后自动关闭，自动评论内容维护在 simplify-reproduction.md。

评论中给出了理想最小复现的完整清单（在相关时不满足以下任意一条都不理想）：

• 不是 monorepo 的一部分；
• 运行不需要密钥；
• 不引用私有 registry 依赖；
• 依赖数量尽可能少；
• 不包含无关的页面/路由；
• 运行不依赖数据库或第三方服务；
• 只包含复现问题所必需的代码；
• 已对照 next@canary 测试，确认问题尚未被修复。

4. good first issue（适合初次贡献）

含义：该 issue 被认为足够友好，是新手参与项目贡献的良好起点。打上此标签时会自动附带 good-first-issue.md 的评论内容。

5. resolved（假定已修复）

含义：维护者假定更新版本的 Next.js 已修复该问题，因此关闭 issue。如果问题仍然存在且仍然相关，issue 作者或关闭前曾评论过的人可以在 14 天内按照自动评论的指引申请重开，自动评论内容维护在 resolved.md。

标签与自动评论的映射在源码中如何落地

以上五类标签的"打标签即发评论"行为并非人工操作，而是配置在 triage.yml 的 label-comments 映射中，label 与评论文件一一对应：

label-comments: |
  {
    "good first issue": ".github/comments/good-first-issue.md",
    "please add a complete reproduction": ".github/comments/invalid-reproduction.md",
    "please simplify reproduction": ".github/comments/simplify-reproduction.md",
    "please verify canary": ".github/comments/verify-canary.md",
    "resolved": ".github/comments/resolved.md"
  }

工作流在 issues.opened、issues.labeled 以及 issue_comment.created（非 stale 标签的 issue）时触发，且跳过 Documentation 类型的 issue。可以看到，triaging.md 文档中描述的"每个标签附带一条行动指引评论"的机制，与仓库中的实际配置完全一致。

已验证（Verified）Issue 的处理

当一个 issue 经过核实被确认为真实问题后，会收到以下之一：

• linear: next
• linear: turbopack
• linear: docs

表示该问题已纳入维护者的追踪范围（按框架本体、Turbopack、文档三条线管理）。此外还可以追加一个或多个区域标签，标明 Next.js 中受影响的具体部分。

文档对此给出了重要保证：已确认（confirmed）的 issue 永远不会被标记为 stale，也不会在解决前被关闭。也就是说，"被 verified 的 issue"和"被自动关闭的 issue"是两条完全分开的生命周期轨道。

已关闭 Issue：重开窗口与自动锁定

14 天重开窗口

当维护者关闭一个未被锁定（unlocked）的 issue 时，会有一条自动评论说明：issue 作者或关闭前曾评论过的人可以在 14 天内申请重开，申请必须包含 Reopen: 字样及理由。这一机制由仓库中的 issue_reopen.yml 工作流支撑。

两周无活动自动锁定

所有已关闭的 PR 和 Issue 在 2 周（14 天）无活动（如新评论、被其他位置引用）后会被自动锁定。这一行为由 issue_lock.yml 工作流实现，其配置可直接对照文档：

• 使用 dessant/lock-threads Action，issue-inactive-days: 14 与 pr-inactive-days: 14；
• 锁定后分别添加 locked 标签；
• 锁定时附带的评论为："This closed issue has been automatically locked because it had no new activity for 2 weeks..."；
• 定时任务通过 cron 0 0,12 * * * 每天运行两次（UTC 0 点与 12 点）。

重开窗口过期之后，文档建议的做法是：用最新的环境与复现细节新开一个 issue，并在其中引用旧 issue。自动关闭类评论（如 invalid-link、verify-canary）本身也会写明下一步行动。

实操要点：一份不会被自动关闭的 Bug 报告

结合 triaging.md 与 bug 报告模板，提交一份"合格"的 bug 报告需要满足：

1. 必填复现链接：指向一个公开的 GitHub 仓库或 CodeSandbox/StackBlitz 沙箱，且必须填在 "Link to the code that reproduces this issue" 栏位中。模板提示中已注明 "Skipping this/providing an invalid link will result in the issue being closed"。推荐直接用官方 reproduction 模板创建，只保留贡献于问题的改动；
2. 必填复现步骤（To Reproduce）：基于复现仓库给出逐步操作；
3. 必填当前/期望行为（Current vs. Expected behavior）：描述清楚观察到的现象与预期差异；
4. 必填环境信息：在项目根目录运行 next info（必要时 npx --no-install next info）并粘贴输出，涵盖操作系统、Node/包管理器版本、next/react 等关键包版本以及 Next.js 配置；
5. 必填受影响区域与阶段：从下拉框中选择受影响的功能区域（如 Middleware、Image (next/image)）与运行阶段（next dev (local)、next build (local)、next start (local)、Vercel (Deployed)、Other (Deployed)），前者会被自动转成标签；
6. 对照 canary 验证：在提交前用 npm install next@canary 测试，避免问题已修复；有条件时进一步定位引入问题的首个 canary 版本；
7. 提交前先搜索既有 issue：模板明确要求先检索既有 issue 并用 +1 点赞代替重复开 issue——这也与自动评论中"用 +1 反应代替 '我也遇到同样问题' 评论"的优先级约定一致。

小结

Next.js 仓库的分诊机制是一套"文档声明 + 工作流执行"完整闭环的制度：triaging.md 定义了标签语义、超时期限与重开规则，triage.yml 负责复现链接校验与标签评论联动，issue_lock.yml 负责 14 天无活动自动锁定，.github/comments 目录下的六个 Markdown 文件则是每个标签背后的标准化行动指引。对贡献者而言，理解这套机制的实际价值在于：把复现质量（最小、公开、可运行、对照 canary）做到位，issue 就能进入 verified 轨道而不是自动关闭轨道。