Refined GitHub 浏览器扩展指南:简化 GitHub 界面并解锁上百项效率功能的完整解析

原创2026-09-29 12:04:181,906 阅读
文章标签:前端开发工具研发协作

Refined GitHub 浏览器扩展指南:简化 GitHub 界面并解锁上百项效率功能的完整解析

Refined GitHub 是一款开源的浏览器扩展,目标只有一个:简化 GitHub 界面并补充大量实用功能。它把开发者高频使用的仓库、Issue、Pull Request、提交、通知、Release 等页面中"令人恼火"的交互细节逐一打磨,让日常开发工作流更顺畅。读完本文,你将掌握它的安装方式、上百项功能的分类全貌、功能开关与自定义配置方法,以及它背后的功能加载与令牌鉴权架构,可以直接上手使用并深入理解其实现原理。


一、项目定位与设计理念

项目在 readme.md 中自我描述为 "Browser extension that simplifies the GitHub interface and adds useful features",即简化 GitHub 界面、添加有用功能的浏览器扩展。它诞生于维护者对 GitHub 日常使用中大量"不方便"的观察与修复意愿——正如 readme 中那句 "So here be dragons" 所说,这是一个高度主观、精心打磨的功能集合。

项目本身是**高度有主见(opinionated)**的:新增功能有很高的门槛,并非所有建议都会被接受,这一点在 readme 的 Customization 一节有明确说明。同时,项目的长期愿景是推动 GitHub 官方注意到这些改进并原生实现,因此 readme 鼓励用户将期望的改进反馈给 GitHub 官方社区。

值得注意的历史背景:readme 专门设有 "Previously part of Refined GitHub" 一节,说明 GitHub 官方曾从该项目中汲取灵感(GitHub 2018 年的 "Paper Cuts" 公告)并原生实现了其中数十项功能,这些功能因此已从扩展中移除。

二、安装与浏览器支持

readme 提供了完整的安装渠道与浏览器支持矩阵:

浏览器 支持范围 发布渠道
Chrome 及其他 Chromium 内核浏览器 桌面端 Chrome Web Store
Firefox 桌面端及 Firefox Android Mozilla Add-ons
Safari Mac、iOS、iPadOS Mac App Store

当前仓库的扩展清单 source/manifest.json(Manifest V3)给出了更精确的版本与权限事实:

  • minimum_chrome_version 为 140;Firefox(含 Android)的 strict_min_version 为 133.0;Safari 的 strict_min_version 为 18.2。
  • 默认 host_permissions 仅包含 https://github.com/* 与 https://api.github.com/*,即默认只在 GitHub 主站生效;optional_host_permissions 为 *://*/*,供按需开启其他域名(如自建 GitHub Enterprise 实例)时动态申请。
  • 声明权限为 storage、scripting、contextMenus、activeTab、alarms,均为最小化授权。
  • 内容脚本(content_scripts)在 document_start 阶段注入 refined-github.css 与 content-script.js,匹配 github.com 与 gist.github.com,并排除登录页。

GitHub Enterprise(企业版)支持

readme 明确说明 GitHub Enterprise 同样受支持。由于企业实例域名不在默认授权范围内,需要借助扩展提供的权限切换机制,为你的企业实例域名单独授予访问权限后即可生效。这与 manifest 中 optional_host_permissions 的设计相互印证。

三、核心亮点功能(Highlights)

readme 首屏用 8 个动图/截图展示了最具代表性的能力,这里逐项展开:

  1. show-whitespace:让代码块中的空白字符(空格、制表符)可视化显示,方便审查 diff 时发现混用缩进。
  2. unreleased-commits:告诉你当前是否在查看仓库的最新版本,或该版本之后是否还有未发布(未打 tag)的提交。
  3. pr-base-commit:显示 PR 的 head 分支落后于 base 分支多少,并给出其基准提交(base commit)。
  4. conversation-activity-filter:在 Issue 与 PR 中隐藏除评论(或未解决评论)之外的所有事件,专注讨论本身。
  5. status-subscription:一键订阅 Issue 的开启/关闭事件,无需进入订阅菜单逐项勾选。
  6. default-branch-button:在目录列表和文件页添加默认分支链接,一键跳回主干。
  7. restore-file:在 PR 中为每个文件添加"丢弃全部更改"按钮,快速回退对某个文件的全部修改。
  8. select-notifications:按类型和状态批量选择通知,配合后续的批量操作提升通知处理效率。

源码示例:show-whitespace 的实现机制

以 source/features/show-whitespace.tsx 为例,可以看到一个功能模块的标准实现:

  • 使用 IntersectionObserver 监听代码行进入视口,才进行空白字符渲染(避免大文件性能浪费);
  • 通过 observe 订阅符合 codeElementsSelector 的代码元素,排除 hunk 行;
  • 最终通过 features.add(import.meta.url, {include: [pageDetect.hasCode], init}) 注册:include 声明仅在包含代码的页面运行,init 是具体执行函数。

这个文件末尾还保留了 TEST URL 注释,方便开发者在真实 GitHub 页面上验证功能——这是项目所有功能文件的通用规范。

四、功能全景:按使用场景分类

readme 将上百项功能按使用场景划分为 16 个类别(以下全部条目均来自 readme 并保持完整):

4.1 仓库(Repositories)

  • repo-header-info 🔥:仓库头部增加 stars、CI、fork 与 private 状态信息。
  • swap-branches-on-compare:分支比较视图添加交换分支的链接。
  • repo-age:侧边栏显示仓库的创建年龄。
  • show-open-prs-of-forks:在 fork 仓库中显示你向原仓库开放的 PR 数量。
  • clean-repo-filelist-actions:让仓库文件列表的按钮更紧凑,为其他功能腾出空间。
  • new-repo-disable-projects-and-wikis:创建仓库时自动禁用 Projects 和 Wikis。
  • sticky-sidebar:让仓库、Issue、PR 的侧边栏在适合视口高度时保持吸顶。
  • link-to-github-io:从仓库页添加访问用户 github.io 站点的链接。
  • github-actions-indicators:workflows 侧边栏显示可手动触发、以及下一次计划调度时间的指示器。
  • quick-repo-deletion:简化仓库删除;为 0-star 仓库添加 "Delete fork" 按钮;支持 shift+alt 点击两步删除。
  • delete-branch:分支页添加删除当前分支的按钮。
  • pr-from-branch:分支页一键打开 PR。
  • archive-forks-link:帮助在归档仓库中查找 forks。
  • repo-avatars:公共仓库头部添加仓库拥有者的头像。
  • small-user-avatars:Issue/PR 列表与提及中,用户名旁显示小头像。
  • action-pr-link 🔥:为 workflow 添加返回运行它的 PR 的链接。
  • mobile-tabs:移动端让 tabs 更紧凑(依赖 extensible-nav 功能)。
  • visit-tag:在指定 tag 浏览文件时,添加查看该 release/tag 本身的链接。
  • actions-run-removal:从 workflow 列表更快地取消或删除运行。
  • rerun-workflow:把 "Re-run jobs" 下拉展开为独立按钮,并添加 r f 快捷键重跑失败任务。
  • extend-repo-tabs:折叠不常用的仓库 tabs(Insights、Security)或空 tabs(Projects、Wiki、Actions),并为 Projects/Wiki 添加计数器。
  • subscribe-releases:一键订阅仓库 releases 的按钮。

4.2 文件管理(File management)

  • download-folder-button:添加下载整个文件夹的按钮(经由 download-directory 服务)。
  • quick-file-edit:从仓库文件列表直接编辑文件。
  • repo-wide-file-finder:在整个仓库启用 File Finder 快捷键(t)。
  • show-associated-branch-prs-on-fork:fork 仓库的分支上显示关联的 PR。
  • html-preview-link:添加预览 HTML 文件的链接。
  • file-age-color:高亮文件列表中最近被修改的项目。
  • previous-version:一键查看文件的上一版本。

4.3 代码(Code)

  • linkify-code:将代码中的 Issue/PR 引用与 URL 链接化。
  • copy-on-y:增强 GitHub 的 y 快捷键,额外复制 permalink。
  • list-prs-for-file:当前文件被某个开放 PR 修改时提醒你。
  • refined-github.css:在 GitHub 未遵循用户偏好处,将 tabs 缩进从 8 空格减为 4 空格。
  • esc-to-deselect-line:esc 快捷键取消选择当前行。
  • list-prs-for-branch:分支提交列表显示影响当前分支的 PR。

4.4 撰写评论(Writing comments)

  • tab-to-indent 🔥:评论字段启用 tab 与 shift+tab 缩进。
  • collapsible-content-button:文本编辑器添加插入可折叠内容(<details>)的按钮。
  • fit-textareas 🔥:评论字段自动随内容调整高度,不再出现滚动条。
  • quick-comment-edit:单击即可编辑任意评论,无需打开下拉菜单。
  • one-key-formatting:按下 [ ` ' " * ~ _ 等 Markdown 符号时包裹选中文本而非替换。
  • clean-rich-text-editor:隐藏不必要的评论字段提示与工具栏项(每项都有键盘快捷键)。
  • quick-mention:在 Issue/PR 中添加 @mention 用户的按钮。
  • table-input:文本编辑器快速插入简化 HTML 表格的按钮。
  • unfinished-comments:提醒隐藏标签页中未写完的评论。
  • quick-review-comment-deletion:编辑审查评论时一键删除。
  • avoid-accidental-submissions:禁用部分提交/PR/Issue 标题字段的 enter 提交快捷键,改用 ctrl+enter,防止误提交。
  • no-self-reference:警告自引用链接,避免出错。

4.5 阅读评论(Reading comments)

  • reactions-avatars 🔥:显示"谁"对评论做出了反应。
  • embed-gist-inline:评论中独立成行的短 gist 直接内嵌展示。
  • comments-time-machine-links:为每条评论添加浏览仓库、浏览关联文件在评论发生时刻状态的链接。
  • show-names:在用户名旁显示用户真实姓名。
  • shorten-links:将 URL 与仓库 URL 缩短为可读引用,如 _user/repo/.file@d71718d。
  • preview-hidden-comments 🔥:内联预览被隐藏的评论。
  • hide-low-quality-comments:隐藏 "+1"、"👍" 等纯反应评论(维护者除外),但仍可手动展开。
  • scrollable-areas:限制超高代码块和引用区域的高度。
  • quick-comment-hiding:简化隐藏评论的 UI。
  • open-issue-to-latest-comment:Issue 列表的"评论"图标直接链接到该 Issue 的最新评论。
  • expand-all-hidden-comments:在长会话中 alt 点击 "N hidden items. Load more..." 一次加载 200 条评论而非 60 条。
  • keyboard-navigation:Issue/PR 会话与 PR 文件列表快捷键:j/k 聚焦下方/上方评论或文件,x 标记文件已读/未读。
  • hidden-content:按 Cmd+F / Ctrl+F 时提示存在被隐藏的评论或文件。

4.6 会话与列表(Conversations)

  • open-all-conversations:一次打开所有可见的 Issue/PR。
  • sticky-conversation-list-toolbar:Issue/PR 列表的过滤器工具栏保持吸顶。
  • conversation-authors:高亮由你或当前仓库协作者打开的 Issue/PR。
  • align-issue-labels:Issue/PR 列表中标签左对齐、置于标题下方。
  • last-update-sort 🔥:将 Issue/PR 默认排序改为 Recently updated(最近更新)。
  • global-conversation-list-filters:全局 PR 搜索中增加 "在你仓库中" 与 "你评论过" 过滤器。
  • clean-conversation-sidebar 🔥:隐藏 Issue/PR 侧边栏中的空区块(或仅隐藏其 "empty" 标签)。
  • clean-conversation-filters:Issue/PR 列表中 Projects 过滤器为空时隐藏。
  • toggle-everything-with-alt:alt+点击按钮或复选框,一次切换所有同类项(折叠评论、延迟 diff 等)。
  • extend-conversation-status-filters:搜索中切换 open/closed/merged 过滤器。
  • bugs-tab:仓库存在带 "bug" 标签的开放 Issue 时添加 "Bugs" tab(依赖 extensible-nav)。
  • pinned-issues-update-time:置顶 Issue 用 "updated" 时间替换 "opened" 时间。
  • mark-pinned:在 Issue 列表中标记置顶项,让重复行一眼可辨。
  • mark-locked:在仓库列表中标记已锁定的 Issue/PR。
  • clean-pinned-issues:将置顶 Issue 布局从并排改为标准列表。
  • quick-label-removal:在 Issue/PR 中添加一键移除标签的按钮。
  • clean-conversation-headers:移除 PR 头部重复信息(如 "User wants to merge X commits from Y into Z")。
  • dim-bots:弱化 bot 的提交与 PR,减少干扰。
  • esc-to-cancel:esc 快捷键取消编辑 PR 标题。
  • no-duplicate-list-update-time:列表更新时间与 open/closed/merged 时间一致时隐藏。
  • linkify-user-labels:将评论与 PR 上的 "Contributor"、"Member"、"Collaborator" 标签链接到作者在仓库的提交。
  • jump-to-conversation-close-event:添加跳转到 Issue/PR 最近一次关闭事件的链接。
  • close-as-unplanned:一键 "close issue as unplanned",替代三步操作。
  • locked-issue:在锁定的 Issue/PR 上显示标签。
  • easy-toggle-hidden-comments:点击头部栏即可切换隐藏评论与已解决/过时审查线程。

4.7 查看 Pull Request(Viewing pull requests)

  • linkify-commit-sha:访问 PR 提交时,添加链接到非 PR 版本的提交。
  • pr-filters:PR 列表添加 Checks 与 Draft PR 下拉过滤器。
  • unclip-checks:展开 checks 面板时自动显示全部检查,无需滚动。
  • pr-approvals-count:PR 列表显示按颜色区分的审查计数。
  • highlight-non-default-base-branch:PR 列表的基础分支非默认分支时高亮显示。
  • hide-inactive-deployments:隐藏 PR 中非活动或失败的部署。
  • previous-next-commit-buttons:Commits tab 页面底部添加重复的提交导航按钮。
  • conflict-marker:PR 列表显示哪些 PR 存在冲突。
  • pr-commit-lines-changed:PR 提交上增加 diff 统计。
  • cross-deleted-pr-branches:PR 中已删除的分支显示删除线。
  • batch-mark-files-as-viewed:PR Files tab 中批量标记/取消标记"已查看":勾选起始文件后 shift 点击另一个文件,中间所有文件一并切换。
  • closing-remarks 🔥:显示合并的 PR 包含的第一个 Git tag,若尚未发布则建议创建 release。
  • pr-jump-to-first-non-viewed-file:点击进度条跳转到 PR 中第一个未查看的文件。
  • view-last-pr-deployment:PR 头部添加打开最新部署的链接。
  • no-unnecessary-split-diff-view:对 split diff 无意义的文件始终使用 unified diff。
  • emphasize-draft-pr-label:让列表中的草稿 PR 更易区分。
  • clean-checks-list:合并检查列表中优先展示失败与待定检查,并取消截断过长检查名。
  • mobile-tabs-pr:缩小 PR tabs,使其无需滚动即可容纳。
  • linkify-pr-review-state:将 PR 列表的审查状态标签("Draft"、"Changes requested" 等)链接化为按状态过滤。

4.8 编辑 Pull Request(Editing pull requests)

  • sync-pr-commit-title 🔥:默认以 PR 标题作为 squash 提交标题;若提交标题被修改则同步更新 PR 标题。
  • update-pr-from-base-branch:为每个 PR 添加 "Update branch | Rebase" 按钮(GitHub 官方虽有此功能,但需逐仓库手动配置)。
  • one-click-review-submission:简化 PR 审查表单,一键式审查类型按钮更快提交 Approve/Request changes。
  • pull-request-hotkeys:PR tab 切换快捷键 g+←/g+→,或 g+1~4。
  • pr-branch-auto-delete:合并 PR 后尽可能自动删除分支(排除 develop、release/* 等已知长生命周期分支名)。
  • one-click-pr-or-gist:一键创建 draft PR 与 public gist。
  • clear-pr-merge-commit-message:清理 PR 合并提交消息,仅保留去重后的共同作者。
  • quick-review:PR 侧边栏添加快速审查按钮,自动聚焦审查文本框,v 快捷键打开审查弹窗。
  • pr-first-commit-title:新 PR 的标题与描述使用首个提交内容。
  • quick-resolve-conflicts:将 "Resolve conflicts" 下拉转换为两个普通按钮。

4.9 提交(Commits)

  • patch-diff-links:提交页添加 .patch 与 .diff 文件链接。
  • more-file-links:PR 与提交中添加快查看 raw 版本、blame、历史记录的链接。
  • one-click-diff-options:Compare 页面添加 "Hide whitespace" 按钮,PR 与 Compare 页面支持 d w 快捷键。
  • extend-diff-expander:加宽 "Expand diff" 按钮,使其跨屏可点击。
  • hide-diff-signs:隐藏 diff 符号(diff 已有颜色区分)。
  • suggest-commit-title-limit:建议将提交与 PR 标题限制在 72 字符内。
  • tags-on-commits-list:提交列表旁显示对应 tag。
  • mark-merge-commits-in-list:提交列表中标记合并提交。
  • deep-reblame:浏览 blame 时 Alt 点击 "Reblame" 会先提取关联 PR 的提交,而非将提交视为单次变更。
  • new-or-deleted-file:用图标标明提交与 PR 中的文件是新增还是删除。
  • easy-toggle-files:点击头部栏切换文件 diff 的展开/折叠。
  • same-branch-author-commits:查看某作者全部提交时保留当前分支与路径。
  • easy-toggle-commit-messages:点击提交框切换提交消息。
  • link-to-compare-diff:将 compare 页面的 "X files changed" 文本链接化为跳转 diff。
  • conventional-commits:以标签形式在提交消息前显示 conventional commit 类型。

4.10 标签与发布(Tags and releases)

  • release-download-count:release 资产旁添加下载计数。
  • releases-tab:添加 Releases tab 与快捷键 g+r(依赖 extensible-nav)。
  • releases-dropdown:release 页面添加 tag 下拉/搜索。
  • create-release-shortcut:Releases 页面添加 c 快捷键创建新 release。
  • tag-changes-link 🔥:为每个 tag/release 添加自上次 tag/release 以来变更的链接。
  • convert-release-to-draft:添加将 release 转为 draft 的按钮。
  • confirm-release:发布 release 时添加确认对话框,防止误发布。
  • link-to-changelog-file:release 页面添加查看 changelog 文件的按钮。

4.11 个人主页(Profiles)

  • user-profile-follower-badge:主页上显示该用户是否关注了你。
  • mark-private-orgs:在个人主页标记私有组织。
  • profile-hotkey:g+m 快捷键访问自己的主页。
  • show-user-top-repositories:添加用户 star 数最高的仓库链接。
  • hide-user-forks:默认从主页过滤 fork 与归档仓库,仅保留源仓库(仍可展开显示)。
  • linkify-user-location:将 hovercard 与主页中的位置信息链接化。
  • conversation-links-on-repo-lists:用户主页仓库 tab 与全局搜索中添加 Issues 与 Pulls 链接。

4.12 通知(Notifications)

  • open-all-notifications:通知页一键打开全部未读通知。
  • unread-anywhere 🔥:全局头部添加任意页面可用的未读通知按钮。
  • select-all-notifications-shortcut:a 快捷键全选可见通知。
  • stop-redirecting-in-notification-bar:按住 Alt 时通知栏操作不再跳转到通知收件箱。
  • last-notification-page-button:添加通知最后一页的链接。
  • pr-notification-link:将 PR 通知指向 Conversation tab 而非可能 404 的 commits 页。
  • sticky-notifications-actions:通知操作栏保持吸顶。
  • clean-notifications:按仓库分组时让通知列表更紧凑。
  • notifications-ui:清理通知页头部,尤其在移动端。

4.13 全局(Global)

  • useful-not-found-page 🔥:404 页面提供可能相关的页面与替代链接。
  • selection-in-new-tab:j/k 导航时用 shift+o 在新标签打开选中项。
  • close-out-of-view-modals:下拉菜单不可见时自动关闭。
  • parse-backticks:补全 GitHub 漏掉的反引号渲染。
  • action-used-by-link:在 Marketplace 查看其他项目如何使用当前 Action。
  • improve-shortcut-help:在帮助弹窗(? 快捷键)中展示 Refined GitHub 全部新快捷键。
  • clean-footer:弱化站点页脚。
  • night-not-found:为全局 404 页添加暗色模式。
  • monospace-textareas:提交消息、描述、release body 等字段使用等宽字体。

4.14 礼仪提醒(Netiquette)

  • netiquette:添加不打扰式的礼仪提醒(旧关闭的 Issue、高活跃 Issue、draft PR 等)。
  • warn-pr-from-master:从默认分支创建 PR 时警告(反模式)。
  • warning-for-disallow-edits:取消勾选 "Allow edits from maintainers" 时警告(对维护者不友好)。

4.15 修复 GitHub 缺陷(Fixes for GitHub shortcomings)

  • github-bugs:对 GitHub 界面应用多种 CSS 修复。
  • hide-navigation-hover-highlight:移除仓库文件浏览器中的文件悬停效果。
  • clean-repo-sidebar:移除仓库侧边栏中不必要或冗余的信息。
  • linkify-branch-references:将 "Quick PR" 页面中的分支引用链接化。
  • actionable-pr-view-file:PR 的 "View file" 指向分支而非提交,使编辑/删除按钮可用。
  • reload-failed-proxied-images:重试因 GitHub 代理限制而加载失败的图片。
  • prevent-link-loss:建议修复被 GitHub 错误缩短的链接。
  • prevent-duplicate-pr-submission:避免误点多次 "Create pull request" 造成重复 PR。
  • prevent-comment-loss:撰写/编辑评论时,预览链接在新标签打开,避免离开页面丢失内容。
  • fix-no-pr-search:搜索未含 is:pr 时重定向到仓库 Issue 列表。
  • clean-readme-url:从仓库 URL 中移除冗余的 readme-ov-file 参数。
  • click-outside-modal:点击弹窗外关闭 checks 列表。
  • linkify-line-numbers:为 GitHub 漏加链接的行号补充链接。
  • sidebar-focus-file:文件树滚动到当前文件。
  • no-modals:禁用降低体验的弹窗。
  • same-page-links:保持链接在当前页打开,"新标签打开"必须是用户的选择而非默认行为。
  • linkify-text:让特定文本可点击,如 Issue 标题与讨论侧边栏中的 Issue 引用。
  • new-milestone-button:milestone 页面添加 "New Milestone" 按钮。
  • mark-private-repos:用醒目的颜色在仓库列表中高亮私有仓库。
  • tab-size:在 GitHub 未遵循用户偏好处,将默认 tab 缩进从 8 字符减为 4 字符。
  • sticky-file-header:滚动代码 diff 时文件头部保持吸顶。
  • sticky-csv-header:横向滚动时 CSV/TSV 预览首列保持固定。
  • reactions-popup:缩小评论反应弹窗,提升可用性。
  • readable-title-change-events:标题变更时间线事件中上下堆叠新旧标题,更易阅读。
  • cmd-enter:修复已关闭 PR 上 cmd+enter 提交评论失效的问题。
  • new-tab-links:ctrl+点击或中键在新标签打开伪链接。

五、源码级解析:功能加载与运行架构

readme 的功能清单只是表象,真正值得开发者研究的是 source/feature-manager.tsx 中统一的加载框架。

5.1 FeatureLoader 声明(运行条件)

每个功能模块通过 features.add(import.meta.url, loader) 注册,loader 的核心字段定义于 FeatureLoader 类型(feature-manager.tsx):

字段 含义 默认值
include 至少一个条件为真才运行(页面匹配) []
exclude 任一条件为真即不运行 []
asLongAs 所有条件必须为真才运行 []
init 功能初始化函数,可传入数组;返回 false 表示当前页不执行 必填
awaitDomReady 是否等待 DOM ready 后才运行 init false
requiresToken 是否要求配置个人访问令牌 false
shortcuts 注册的快捷键及其帮助文案(仅加入帮助页) {}
deduplicate 通过选择器去重,避免重复注入(已标记为废弃) false

运行条件的判定逻辑在 source/helpers/feature-utils.ts 的 shouldFeatureRun 中:asLongAs 全部为真 且 include 至少一个为真 且 exclude 全部为假,功能才会真正初始化。include 若传空数组会被直接判定为错误("run nowhere"),从框架层面杜绝了"永远不运行"的无效注册。

5.2 add() 的执行流程

feature-manager.tsx 的 add() 完整展示了运行链路:

  1. 读取全局就绪的选项(globalReady 会并行等待选项、内容脚本开关、热修复、二分定位等就绪);
  2. 通过 isFeatureDisabled 检查用户是否关闭了该功能(CSS-only 功能被关闭时会向 <html> 写入 rgh-OFF-<id> 属性,由 CSS 选择器接管禁用,见 feature-manager.tsx);
  3. 逐项执行 init,每个功能持有独立的 AbortController;页面发生 turbo:render / soft-nav:react-done 软导航时,循环重新评估运行条件(这正是 GitHub 现在基于 Turbo 的 SPA 式导航下功能依然可用的关键);
  4. 浏览器前进/后退触发 turbo:visit 时,unloadAll 会 abort 所有控制器,保证监听器与观察器被干净清理。

5.3 入口注册与 CSS-only 功能

source/refined-github.ts 是全部功能的"总目录":首先引入 rgh-deduplicator(核心功能,服务 deduplicate 键),然后按类别导入约 200 个功能模块。其中存在一批纯 CSS 功能(如 github-bugs.css、tab-size.css、clean-footer.css、sticky-file-header.css 等),它们不经过 JS 执行,但仍可通过选项关闭(被关闭时由 rgh-OFF- 属性实现 CSS 级禁用)。文件注释还明确了一条工程约定:"JS 功能所属的 CSS 不得在此导入,应在其 .tsx 中自行导入",保证了样式与逻辑的内聚。

5.4 功能 ID 与命名

source/helpers/feature-helpers.ts 中的 getFeatureId 从模块 URL 提取文件名作为功能 ID;getIdentifiers 进一步生成 rgh-<id> 类名,供 DOM 标记与测试使用。功能改名由 source/feature-renames.json 维护,source/options-storage.ts 的迁移逻辑会在升级时把旧开关值迁移到新 ID 下,保证用户设置不丢失。

六、自定义与配置

readme 的 Customization 一节明确了扩展的可配置性:

大多数功能都可以关闭——前提是它们是 JavaScript 实现的功能;对于 CSS 样式,你可以在扩展选项中用自定义 CSS 覆盖默认样式。

6.1 配置项全解

默认配置定义在 source/options-storage.ts:

配置键 默认值 说明
feature:<id> true 每个功能一个独立开关,对应 readme 中列出的全部功能 ID
customCss '' 自定义 CSS,注入到页面 <head> 覆盖默认样式
personalToken [''] 个人访问令牌数组,支持配置多个(应对多账号场景)
actionUrl 'https://github.com/' 当前生效的 GitHub 实例地址(企业版切换时变化)
logging false 是否在控制台输出功能运行日志
logHttp false 是否输出 HTTP 请求日志

配置存储基于 webext-options-sync-per-domain,支持按域名隔离配置;升级迁移逻辑处理了功能重命名(feature-renames.json)、旧字段改名(logHTTP→logHttp、customCSS→customCss)与令牌数组规范化(过滤空字符串),并通过 removeUnused 自动清理已移除功能的残留开关。

6.2 定位页面上的具体功能

当你在页面上看到某个改动想知道它属于哪个功能时,可以右键扩展图标,使用 "Reload page and identify feature…" 菜单(实现见 source/options/identify-feature.ts):它会重载页面并进入"二分定位"模式,自动定位当前页面由哪些功能驱动,从而精确找到对应的开关与源码。

七、个人访问令牌(Token)的作用

readme 未展开介绍,但 source/github-helpers/github-token.ts 揭示了依赖令牌的功能运作方式。凡声明 requiresToken: true 的功能(如仓库信息增强、PR 关联查询等),运行前会调用 expectToken:

  • getToken 支持多令牌:若配置了多个令牌,会按当前登录用户匹配对应令牌(用户名查询结果缓存一年);
  • baseApiFetch 向 api.github.com 发起带 Authorization: token <token> 的请求,并可切换 apiBase 以支持企业版;
  • expectTokenScope 会校验令牌 scope,缺失时给出明确的错误提示(提示在 GitHub 设置页调整令牌权限);
  • parseTokenScopes 兼容 classic 与 fine-grained 两类令牌(缺少 X-OAuth-Scopes 头时按 fine-grained 处理)。

因此,若要解锁依赖 API 的功能,需要在扩展选项中填入具有合理 scope(如 repo、read:project)的个人访问令牌。这部分设置入口与验证逻辑由 source/options/ 下的 token-input、validate-token 等模块提供。

八、本地构建与开发

仓库根目录的 package.json 展示了完整的工程脚本(Node.js >= 24,npm 管理):

  • npm run build:并行执行 Svelte 类型检查(build:svelte)、TypeScript 检查(build:typescript)与 Rollup 打包(build:bundle);
  • npm run test:并行执行 Vitest 单元测试与全部 lint/构建检查;
  • npm run start / npm run watch:进入监视模式,实时编译 TypeScript、Svelte 与 bundle;
  • npm run new:通过脚本脚手架创建新功能模块;
  • npm run pack:safari / prepare:safari:处理 Safari 版本打包(对应 safari/ 目录中的 Xcode 工程);
  • npm run lint / format:ESLint 与 dprint 格式化(配置见 eslint.config.js 与 dprint.json)。

开发者模式下,将 distribution/ 目录作为"已解压的扩展"加载到浏览器即可本地体验(webExt 配置中已为 Firefox/Chromium 预留了测试 profile 与启动页)。

九、参与贡献

readme 的 Links 一节指向项目的贡献指南(wiki 的 Contributing 页面),并重申了项目的高度主观性:新增功能门槛很高(readme 明确提示存在 "Can you add this feature?" 的高标准讨论),但同时欢迎任何建议与讨论。结合前文可见,该项目从功能清单、运行框架到测试(如 eslint-rules/ 中为 CSS 文档、嵌套等制定的工程规范,以及 source/helpers/ 下大量 .test.ts 单测)都有极高的工程标准,是学习浏览器扩展工程化与"功能即模块"架构的优秀开源范本。


小结:Refined GitHub 用"一个功能一个文件 + 统一加载框架"的方式,把近 200 项 GitHub 体验改进组织成可独立开关、可测试、可迁移的模块体系。从安装到自定义,从功能清单到源码架构,本文覆盖的路径足以让你将它纳入日常工作流,并在需要时深入到任意功能模块中理解其实现。

登录后查看全文
refined-github