目录
4509 字
23 分钟
开源维护者的倦怠:不是 issue 太多,而是义务没有边界

一、不敢打开 GitHub 的那个星期#

一个只有三个直接依赖的小库,4.2k star,每周新增十几个 issue。维护者下班回家,手机弹出当天第六条 @:「在吗?这个问题什么时候修?」维护者关掉通知,第二天没有打开 GitHub。再往后,仓库里多了四十多个未回复的 issue,和一条「这个项目还维护吗」的讨论。

从外面看,这个项目的代码没坏,CI 还是绿的,下载量也没掉。从里面看,维护者已经在考虑归档。

很多人把这种状态归因于「issue 太多」。数量确实是一部分,但真正消耗人的,是另外三件事:

  • 时间没有边界:任何时刻的通知都被默认需要回应;
  • 角色没有边界:用户把维护者当成供应商、客服和产品经理的合体;
  • 责任没有边界:兼容性、安全、文档、下游项目的故障,都被算到同一个人头上。

工作量可以用周末补回来,边界消失不行。边界一旦消失,休息也像是在欠债。

这篇文章不打算劝人「调整心态」,也不打算把倦怠说成个人修养问题。它想讨论的是:维护者能不能用一些具体的接口设计,把无上限的义务变成有范围的工作。

二、先把维护工作拆成四本账#

「维护开源项目」听起来是一件事,实际至少是四类工作。它们的频率、可见度和消耗完全不同:

工作典型内容是否产生 commit是否被看见消耗来源
写代码修 bug、加功能、重构是高注意力切换
评审看 PR、给修改意见、等作者更新否中来回沟通
支持回答用法问题、排查环境、解释文档否低重复劳动与情绪劳动
治理定范围、triage、发版、安全响应、找接班人否很低决策责任

只按 commit 衡量贡献的模型,会系统性地低估后两本账。一个维护者这周没写一行代码,但关了二十个重复 issue、把三个问题转成 Discussions、发了一次安全补丁、拒绝了一个会扩大范围的功能请求——这些都不出现在 contribution graph 里,却决定了项目能不能继续被维护。

倦怠往往不是「我做了太多代码」,而是「我做了太多不计入任何账本的事,而且它们没有下班时间」。

三、先量出来:四个数字#

在谈边界之前,先知道边界在哪里被突破。下面四个指标不需要复杂工具,GitHub CLI 加一段脚本就能算。注意 --limit 1000 会截断更大的仓库,issue 超过一千条时需要分页或改用 GraphQL。

3.1 issue 流入与关闭#

Terminal window
gh issue list --repo owner/repo --state all --limit 1000 \
--json number,createdAt,closedAt,labels > issues.json
import { readFileSync } from "node:fs";
const DAY = 86_400_000;
const now = Date.now();
const issues = JSON.parse(readFileSync("issues.json", "utf8"));
const opened = issues.filter((i) => now - Date.parse(i.createdAt) <= 90 * DAY);
const closed = issues.filter(
(i) => i.closedAt && now - Date.parse(i.closedAt) <= 90 * DAY,
);
console.log(`近 90 天:新开 ${opened.length},关闭 ${closed.length}`);
const open = issues.filter((i) => !i.closedAt);
const ages = open
.map((i) => Math.floor((now - Date.parse(i.createdAt)) / DAY))
.sort((a, b) => a - b);
const quantile = (p) => ages[Math.ceil(p * ages.length) - 1] ?? 0;
console.log(`未关闭 ${open.length},年龄 p50 ${quantile(0.5)} 天,p90 ${quantile(0.9)} 天`);

如果连续三个月的流入都高于关闭,积压更可能是结构性的,不是「最近比较忙」。这时加功能只会让流入更快;先处理 triage 和范围,才有意义。

3.2 未关闭 issue 的年龄分布#

p50 和 p90 的差距比总数更有信息量。p50 是 10 天、p90 是 400 天,说明大部分问题处理得动,但有一批长期没人碰;p50 就是 180 天,说明 triage 本身停了。

年龄大不一定是坏事。有些 issue 是有价值的长期需求,只是没排期。关键是它有没有被明确标记:是「等社区贡献」,还是「不在范围」,还是「我们也不知道」。没有标记的长期开启,等于把不确定性留给每一个来访者。

3.3 首次响应时间#

首次响应不等于修复。它可以只是一句「收到了,需要最小复现」,也可以是把问题转到 Discussions。把「首次响应」和「修复完成」分开统计,维护者才敢承诺前者。

这个指标用 gh api 拉每个 issue 的第一条评论时间可以算,但更简单的做法是抽样:每周随机看十条新 issue,记录从创建到第一条维护者回复的天数。样本小,趋势仍然看得见。

3.4 bus factor:有几个人能独立发版#

这个问题比前面三个都尖锐:如果维护者这周生病,谁能发一个安全补丁?

能独立发版至少需要:仓库写权限、发布凭据、CI 流程、版本策略、变更日志习惯。缺一项,bus factor 就是 1。一个人维护的项目不一定有问题,但一个人维护且没有文档化的发布流程,是把项目的可用性绑在个人的健康上。

四、边界不是冷漠,是接口设计#

维护者常把「设边界」理解成「对用户不客气」。其实边界更像 API 的输入校验:它不是拒绝所有请求,而是把请求整理成可处理的形状。

4.1 用 issue 表单替代自由文本#

GitHub 的 issue forms 可以强制收集版本、最小复现和期望行为:

.github/ISSUE_TEMPLATE/bug.yml
name: Bug report
description: 可复现的缺陷
body:
- type: input
id: version
attributes:
label: 版本
placeholder: 例如 2.3.1
validations:
required: true
- type: textarea
id: repro
attributes:
label: 最小复现
description: 一段能独立运行的代码,或一个最小仓库链接
validations:
required: true
- type: textarea
id: expected
attributes:
label: 期望行为与实际行为
validations:
required: true

再关掉空白 issue,把使用问题引到 Discussions:

.github/ISSUE_TEMPLATE/config.yml
blank_issues_enabled: false
contact_links:
- name: 使用问题
url: https://github.com/owner/repo/discussions
about: 请先在 Discussions 提问,issue 区只处理可复现的缺陷

表单不是官僚主义。它把「你能不能帮我看看」转换成「版本、复现、期望」三样可核对的信息。很多 issue 在这一步就会自我解决:用户为了写复现,先发现了自己的配置错误。

4.2 把支持预期写进仓库#

在一眼能看到的地方写清楚响应预期,比事后解释省力:

SUPPORT.md
## 支持范围
- 这个项目由维护者在业余时间维护,不提供商业 SLA。
- 可复现的缺陷会进入 triage;功能请求不承诺排期。
- 使用问题请在 Discussions 提问,issue 区不处理。
- 安全问题请按 SECURITY.md 的流程私下报告。

这段话的重点不是免责,而是把隐式契约变成显式契约。用户仍然可以提需求,但不再默认「提了就会有人做」。

4.3 公开渠道优先#

「可以私聊问个问题吗」是边界侵蚀的常见入口。一对一的消息没有搜索价值,也无法被社区复用;同样的问题会被不同的人重复问。把讨论留在 issue 或 Discussions,既减少重复劳动,也让后来的人能搜到答案。

对维护者来说,一个实用的规则是:私聊只处理安全问题和私密数据,其余都请回到公开渠道。 这句话可以直接放在仓库的 CONTRIBUTING 里。

五、triage 不是收件箱,是决策树#

很多维护者把 triage 做成「把 issue 看一遍,能修就修」。这会把自己拖进每一个问题。更可持续的做法是先把 issue 分到几个确定的桶里,再决定谁来做:

信号动作谁来做
安全漏洞转私下渠道,公开 issue 只留「已收到」维护者
没有最小复现标记 needs-info,给出补充模板机器人或 triage 角色
功能请求转到 Discussions,说明是否在范围内triage 角色
使用问题转 Discussions 或指向文档机器人或 triage 角色
重复问题关联合并,关闭新的triage 角色
与项目范围不符明确说明范围,标记 not planned维护者

这张表的价值在于:除了「安全」和「范围判断」,大部分分诊工作不需要维护者本人。把 triage 权限授予活跃贡献者,是成本较低的减负方式,也是培养接班人的开始。

5.1 三段可以直接复制的回复#

拒绝功能请求时,把「不」说清楚,但不攻击提问的人:

Thanks for the detailed proposal. This is outside the scope I can maintain:
the project intentionally stays small and doesn't include X. I'm closing this
as not planned. If your use case needs it, a plugin or a fork may be a better
fit, and I'm happy to link it from the README.

关闭缺少复现的 issue 时,留下重开的路径:

I can't reproduce this with the information provided. I'll close it for now so
the issue list stays actionable. If you can share a minimal reproduction
(a small repo or a runnable snippet), I'll reopen and take another look.

需要暂停维护时,提前说明,而不是消失:

I'm taking a break from maintainership until <date>. Security reports will
still be handled via SECURITY.md. Feature requests and general questions
won't get a response during this period. Thanks for understanding.

这三段话的共同点是:给出决定、给出理由、给出下一步。用户不一定满意,但不会因为不知道状态而反复追问。

六、自动化只处理「可判定」的部分#

自动化能省时间,但也会放大错误的规则。判断标准很简单:这个动作是否只依赖可核对的事实?

  • 可以自动:缺版本、缺复现、超过 30 天没有补充信息、重复链接;
  • 不要自动:功能是否有价值、issue 是否重要、用户是否「态度不好」。

一个常见的反面例子是把 stale bot 配成「所有 issue 60 天没动静就关闭」。真正的问题往往没人回复,60 天后被机器人关掉,报告者以为项目放弃了,维护者也失去了一个本该处理的信号。

更稳妥的配置是只对 needs-info 生效,并且先留言、再关闭:

- uses: actions/stale@v9
with:
only-issue-labels: needs-info
days-before-issue-stale: 30
days-before-issue-close: 14
stale-issue-label: stale
stale-issue-message: >
这个 issue 还缺少最小复现或版本信息。请在 14 天内补充;
否则我会先关闭,之后可以随时重开。
close-issue-message: >
因缺少可复现信息关闭。补充信息后欢迎重开。

这条规则的边界很清楚:它不判断问题重不重要,只判断「有没有足够信息让别人动手」。前者需要人,后者可以交给机器。

七、发布节奏:把「随时」改成「按批次」#

维护者的时间很容易被 release 切碎:一个紧急修复、一次依赖升级、一个文档改动,各自触发一次发版。发版本身不复杂,复杂的是每次都要重新回忆流程、检查变更、写说明。

把发布改成固定节奏,能同时降低认知负担和用户预期:

  • 固定窗口:例如每两周一次常规发布,紧急安全修复随时插队;
  • 批次合并:小改动先合进主干,到窗口一起发,减少重复的发布检查;
  • 明确支持窗口:只维护最近两个 minor 版本,旧版本只接收安全修复;
  • 变更日志随 PR 写:合并时就把「用户能感知的变化」写进 changelog,而不是发版前补。

固定节奏的另一个好处是,它给了维护者一个可以引用的时间点。「这个修复会进下个版本」比「我尽快」更可核对,也更不容易变成无限期的承诺。

对 LTS 要格外谨慎。承诺一个自己没时间支持的长周期版本,等于给未来签了一张空白支票。宁可把支持窗口写短,也不要到期后悄悄失联。

八、共同维护、文档化与退出#

8.1 把发布流程写成 runbook#

bus factor 为 1 的项目,通常不是因为没人愿意帮忙,而是因为「怎么发版」只存在维护者脑子里。一份最小 runbook 应该包含:

  • 发布前的检查项:CI、变更日志、版本号、迁移说明;
  • 发布命令与凭据位置(凭据本身放密码管理器,不写进仓库);
  • 发布后的验证:安装、冒烟测试、回滚方式;
  • 安全问题的处理流程与联系人。

这份文档不一定公开,但至少要让第二个维护者能照着做一遍。

8.2 分阶段放权#

给权限不是二选一。可以从 triage 开始,再到合并小 PR,再到独立发版:

阶段权限观察点
观察者无写权限评论质量、是否理解项目范围
triage管理 issue 与标签分类是否稳定、回复是否得体
评审者批准 PR是否能守住兼容性与测试标准
发布者合并与发版是否能独立完成一次发布

放权的难点不是技术,而是信任。比较务实的做法是先从「低风险、可回滚」的权限开始,配合清晰的决策记录,而不是等一个「完全可靠的人」出现。

8.3 退出不是失败#

项目可以归档,也可以转交。两种都比「人消失了但仓库还开着」更负责:

  • 转交:提前在 README 与 issue 里说明寻找维护者,列出需要接手的工作与权限;
  • 归档:发一个最终版本,写明归档原因、最后支持的版本与安全建议,把 issue 区设为只读;
  • 降级维护:只修安全问题,不再接受功能请求,并在 README 顶部写清楚。

退出时对用户伤害较大的行为不是「不维护了」,而是「看起来还在维护」。明确的结束比无限的沉默更可控。

九、钱能买时间,买不来边界#

赞助和商业支持能让维护者少加几天班,但它不会自动解决边界问题。事实上,一旦有了付费用户,新的义务会随之出现:响应时间、路线图、专属支持。

如果项目接受赞助,建议同时写清楚「钱买到了什么」:

  • 买到的是维护者的时间,不是某个功能的排期;
  • 付费支持可以承诺响应窗口,但不能承诺「所有需求都做」;
  • 企业用户如果依赖某个修复,可以考虑 upstream 贡献、赞助专项或雇佣维护者,而不是在 issue 里反复催促。

下游项目也需要承担一部分责任。一个被成千上万个项目依赖的库,如果只有一个人在业余维护,那么风险不是维护者「不够努力」,而是依赖方没有为这份基础设施付费或分担。

十、一个 30 天的最小行动方案#

如果现在的状态是「每周都在救火」,可以按下面四周做一次收敛:

周动作产出
第 1 周拉 issue 数据,算流入/关闭、年龄分布、bus factor一张基线表,知道问题在哪
第 2 周加 issue 表单、SUPPORT.md、关闭空白 issue新 issue 的信息完整度上升
第 3 周建 triage 决策树,找一个活跃贡献者给 triage 权限分诊不再只经过一个人
第 4 周关闭一批 needs-info,写发布 runbook,定下发布窗口待办变短,流程可交接

不用一次做完。先做第 2 周的表单,通常就能立刻减少重复提问;先算第 1 周的数字,才能说服自己「不是我不够快,是流入本来就在增加」。

十一、检查清单#

  • issue 是否有表单约束版本、复现与期望? 没有的话,先补这个。
  • 支持预期是否写在仓库里? 响应时间、支持范围、安全问题渠道。
  • triage 是否有明确规则? 每一类 issue 应该去哪里、由谁处理。
  • 是否有至少一个人能独立发版? 如果没有,先写 runbook。
  • 自动化是否只处理可判定的事实? 不要用 stale bot 判断价值。
  • 发布是否有固定节奏和支持窗口? 「随时」会变成「永远」。
  • 功能请求是否有拒绝模板? 拒绝要给出范围与替代方案。
  • 是否把私聊引导回公开渠道? 重复问题应该在公开地方被复用。
  • 是否记录了长期未关闭 issue 的状态? 等贡献、不在范围、还是待定。
  • 退出预案是否写清楚? 转交、降级维护、归档,都比沉默好。

十二、小结#

  • 倦怠的根源通常不是 issue 数量,而是时间、角色与责任三条边界同时消失。 只减少数量,不设边界,休息也会像欠债。
  • 维护有四本账:代码、评审、支持、治理。 后两本不产生 commit,却消耗了大量时间。
  • 先量流入、关闭、年龄分布和 bus factor。 没有数字,容易把结构性问题误判成个人效率问题。
  • 边界是接口设计,不是冷漠。 issue 表单、支持政策、triage 决策树,都是把请求整理成可处理的形状。
  • 自动化只处理可判定的事实。 缺信息可以自动关闭,价值判断不能。
  • 发布节奏和支持窗口要写出来。 「我尽快」不是承诺,「下个版本」才是。
  • 共同维护从分阶段放权开始。 先 triage,再评审,再发版;同时把流程写下来。
  • 退出是维护的一部分。 转交、降级维护、归档,都比「看起来还在维护」更负责。

参考来源#

开源维护者的倦怠:不是 issue 太多,而是义务没有边界
https://www.hehonglei.cn/posts/open-source-maintainer-burnout-boundaries/
作者
Honglei He
发布于
2026-11-13
许可协议
CC BY-NC-SA 4.0