Refined GitHub 浏览器扩展指南:简化 GitHub 界面并解锁上百项效率功能的完整解析
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 个动图/截图展示了最具代表性的能力,这里逐项展开:
- show-whitespace:让代码块中的空白字符(空格、制表符)可视化显示,方便审查 diff 时发现混用缩进。
- unreleased-commits:告诉你当前是否在查看仓库的最新版本,或该版本之后是否还有未发布(未打 tag)的提交。
- pr-base-commit:显示 PR 的 head 分支落后于 base 分支多少,并给出其基准提交(base commit)。
- conversation-activity-filter:在 Issue 与 PR 中隐藏除评论(或未解决评论)之外的所有事件,专注讨论本身。
- status-subscription:一键订阅 Issue 的开启/关闭事件,无需进入订阅菜单逐项勾选。
- default-branch-button:在目录列表和文件页添加默认分支链接,一键跳回主干。
- restore-file:在 PR 中为每个文件添加"丢弃全部更改"按钮,快速回退对某个文件的全部修改。
- 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" 下拉展开为独立按钮,并添加
rf快捷键重跑失败任务。 - 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 页面支持
dw快捷键。 - 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:添加
Releasestab 与快捷键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() 完整展示了运行链路:
- 读取全局就绪的选项(
globalReady会并行等待选项、内容脚本开关、热修复、二分定位等就绪); - 通过
isFeatureDisabled检查用户是否关闭了该功能(CSS-only 功能被关闭时会向<html>写入rgh-OFF-<id>属性,由 CSS 选择器接管禁用,见 feature-manager.tsx); - 逐项执行
init,每个功能持有独立的AbortController;页面发生turbo:render/soft-nav:react-done软导航时,循环重新评估运行条件(这正是 GitHub 现在基于 Turbo 的 SPA 式导航下功能依然可用的关键); - 浏览器前进/后退触发
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 体验改进组织成可独立开关、可测试、可迁移的模块体系。从安装到自定义,从功能清单到源码架构,本文覆盖的路径足以让你将它纳入日常工作流,并在需要时深入到任意功能模块中理解其实现。