Dark Reader 贡献指南实战站点修复规则、Dev Tools 与本地构建调试全解析【免费下载链接】darkreaderDark Reader Chrome and Firefox extension项目地址: https://gitcode.com/gh_mirrors/da/darkreaderDark Reader 是一款开源的浏览器暗色模式扩展MIT 协议任何人都可以通过多种方式为它贡献力量赞助、翻译、提交站点修复规则、报告 Bug 或开发新功能。本文基于仓库根目录的 CONTRIBUTING.md 编写系统讲解Dark Reader 锁协议、dark-sites 与站点修复配置文件的规则语法、Dev Tools 的使用流程以及本地构建调试环境搭建并结合 src/generators/、src/config/ 与 tests/unit/config/config.tests.ts 等源码佐证底层实现帮助贡献者快速上手并提交高质量的 Pull Request。贡献方式总览Dark Reader 的贡献入口非常多样不需要精通 TypeScript 也能参与赞助通过 Open Collective 赞助项目开发帮助维护者投入更多时间维护与开发新功能。翻译改进或新增 src/_locales 目录下的语言文件如zh-CN.config、ja.config等可参考浏览器扩展国际化支持的语言代码表。站点修复向 src/config/dark-sites.config、src/config/dynamic-theme-fixes.config、src/config/inversion-fixes.config 提交规则修正本已为暗色的站点或渲染错误的元素——这是最主流、门槛最低的贡献方式下文将重点展开。功能开发与 Bug 修复先提交 issue 讨论、获得维护者批准后再提交代码。让网站禁用 Dark Readerdarkreader-lock 协议如果你的网站不希望被 Dark Reader 处理例如站点本身已提供暗色模式可以在文档中嵌入一个meta标签作为锁name属性取值为darkreader-lock且必须是head标签的子节点。静态禁用在 HTML 的head中加入head meta namedarkreader-lock /head动态禁用若浏览器已解析出document.head可以用 JavaScript 动态插入锁const lock document.createElement(meta); lock.name darkreader-lock; document.head.appendChild(lock);底层实现原理从源码看锁的检测是实打实的运行逻辑而非文档层面的约定。在 src/inject/dynamic-theme/index.ts 中isDRLocked()L556-L558通过document.querySelector(meta[namedarkreader-lock])判断是否存在锁addMetaListener()L539-L547注册一个MutationObserver监听document.head的子节点变化一旦发现darkreader-lock标签出现立即断开观察器并调用removeDynamicTheme()卸载整个暗色主题在 L541-L545 中锁出现后动态主题会被整体移除这也解释了为什么动态插入锁同样有效——MutationObserver 会捕获到 DOM 变化。仓库还利用同一机制防止多个暗色插件互相冲突interceptOldScript()L577-L595会临时注入一个darkreader-lock标签以接管页面随后在微任务中移除并继续自身逻辑。提交本已为暗色的站点dark-sites.config如果某个网站默认就是暗色主题Dark Reader 不应再对它应用暗色滤镜否则会出现越滤越亮的异常此时应将其加入 src/config/dark-sites.config。提交前必须满足以下条件整个网站含所有子页面默认即为暗色且与系统偏好色系无关URL 必须是真实地址不允许任何形式的跳转/重定向网站必须完整上线处于设计、开发阶段或含即将上线搬迁中等占位内容的不予接受。该文件为纯文本列表每行一个站点域名必须保持字母序如0bin.net、12bytes.org等见 dark-sites.config 第 25 行起。该文件同样支持*.xxx.com形式的通配域名条目见 L1-L24。测试 tests/unit/config/config.tests.ts 会读取该文件并校验格式与排序。修复错误反色三份站点修复配置文件如果页面中某些元素没有被正确反色或样式异常需要按渲染模式选择对应的修复文件渲染模式修复文件Dynamic动态模式src/config/dynamic-theme-fixes.configFilter / Filter滤镜模式src/config/inversion-fixes.config提交时请注意保持按 URL 字母序排列、选择尽量短的选择器、维持文件现有代码风格。使用 Dark Reader Dev Tools 生成修复Dark Reader 内置了开发者工具可直接在真实网页上试验规则并即时预览适合修复暗底上的暗图标过亮背景透明图片缺少白色背景等小问题。典型场景Dynamic 模式页面出现半暗半亮属异常可能需要微调单个元素或容器Filter 模式常见做法是把页面上原本就是暗色的元素反转回来。逐步操作流程打开浏览器开发者工具Chrome 按F12Firefox 打开 InspectorCtrlShiftC点击左上角的元素选择器Firefox 默认启用选中一个反色异常的元素为该元素或同类元素挑选合适的 CSS 选择器例如元素带classicon small时可用.icon点击浏览器工具栏的 Dark Reader 图标打开弹窗切换到More标签点击底部的⛭ All settings按钮在左侧切换到Advanced分区点击底部的️ Dev tools按钮可选切到底部的Per Site Editor标签输入要更新或新增的域名按下一节的规则语法编辑/新增包含 URL 与选择器的规则块点击Apply分别在Light与Dark两种模式下检查页面效果修复生效后打开 dynamic-theme-fixes.config 或 inversion-fixes.config点击Edit需登录 GitHub把 Dev Tools 中的修复块按 URL 字母序粘贴进去填写简短的修改说明点击Propose file change→ 检查改动 →Create pull request。提交 PR 后GitHub Actions 会在后台自动运行代码风格校验几分钟内完成出现红叉时点击Details查看错误并修改 PR出现绿勾表示校验通过随后由 Dark Reader 维护者 review 并合并你的修复将随新版本推送给所有用户。Editor Rule 语法详解Dynamic 模式规则块dynamic-theme-fixes.configdynamic-theme-fixes.config example.com INVERT .icon CSS .wrong-element-colors { background-color: ${white} !important; color: ${black} !important; } IGNORE INLINE STYLE .color-picker IGNORE IMAGE ANALYSIS .logo规则块由域名头与分隔线之间加若干规则命令组成各命令的语义与使用要点如下规则说明备注 / 示例INVERT反转指定元素Dynamic 模式下仅用于暗色背景上不可见的暗色图片Filter 模式下用于反转页面上本就是暗色的元素如图片、视频CSS向页面注入自定义 CSS每条属性必须加!important防止被其他样式表覆盖Dynamic 模式支持${COLOR}模板COLOR为反色前的颜色值例如${white}在暗色模式下会变成${black}IGNORE INLINE STYLE跳过对匹配元素内联样式的分析例p stylecolor: red的style属性将不再被修改IGNORE IMAGE ANALYSIS禁止对匹配选择器的背景图片做图像分析—从源码看这些命令并非文本约定而是有真实的解析实现dynamic-theme-fixes.config由 src/generators/dynamic-theme.ts 中的parseDynamicThemeFixes()L21-L32解析命令到字段的映射定义在dynamicThemeFixesCommandsL13-L19中除上文四种外还支持IGNORE CSS URL忽略指定 CSS 文件中的样式。解析结果会进入DynamicThemeFix类型见 src/definitions.d.ts供生成器使用。该文件当前已有超过 4 万行修复规则如全局*块的 Google 翻译气泡、vimvixen-hint提示条等见 dynamic-theme-fixes.config 第 1 行起贡献时请善用 Dev Tools 而非手写长选择器。URL 头书写规则以域名开头如example.com省略www前缀若修复只针对特定子域应写完整子域如sub.domain.com站点在不同地区使用不同顶级域时可用通配如example.*同一修复适用于多个域名/子域时可分行列出最流行的域名放在第一行example.com sub.example.com example.mirror.com通配符*属于最后手段应尽量避免使用。动态变量Dynamic Variables为背景色或文字色做修复时不要硬编码颜色如#fff、#000、black、white而应使用基于用户设置动态生成的 CSS 变量dynamic-theme-fixes.config example.com CSS .logo { background-color: var(--darkreader-neutral-background) !important; } .footer p { color: var(--darkreader-neutral-text) !important; }可用变量完整列表变量说明适用场景--darkreader-neutral-background与用户设置对应的中性背景色主要用于背景色错误的元素--darkreader-neutral-text与用户设置对应的中性文字色用于文字颜色错误的元素--darkreader-selection-background用户设置的背景色即用户 UI 中的 Background Color 设置--darkreader-selection-text用户设置的文字色即用户 UI 中的 Text Color 设置在仓库的修复规则中这些变量被大量使用例如div.mermaid-viewer-control-panel .btn同时使用--darkreader-neutral-background与--darkreader-neutral-text见 dynamic-theme-fixes.config L66-L69可作参考。Filter / Filter 模式修复inversion-fixes.configinversion-fixes.config example.com INVERT .icon .button #player NO INVERT #player * REMOVE BG .bg-photo CSS .overlay { background: rgba(255, 255, 255, 0.5); }要点Filter 模式的工作原理是整体反转整张页面再把不需要反转的元素图片、视频等通过INVERT段反转回来若某个已反转元素内含有显示异常的内容如图片用NO INVERT规则排除REMOVE BG会移除元素的背景图片并强制使用黑色背景CSS规则与 Dynamic 模式类似Filter 模式不支持${COLOR}模板。底层解析同样有源码依据parseInversionFixes()位于 src/generators/css-filter.tsL219-L225 定义了INVERT/NO INVERT/REMOVE BG与CSS等命令映射。inversion-fixes.config的全局*块见 inversion-fixes.config 第 1 行起默认对img、video、object、svg image及各类内联背景图执行INVERT并在NO INVERT中排除input等元素。添加新功能或修复 Bug流程约定若要新增功能或修复 Bug请先在 GitHub 提交 issue若尚不存在与活跃贡献者讨论并等待批准再动手实现。本地构建与调试以 Node.js 环境为例安装 Node.jsLTS 版本在项目根目录执行npm install安装开发依赖执行npm run debug构建调试版本。package.json中debug对应的命令为node --max-old-space-size3072 tasks/cli.js build --debug见 package.json L13构建产物输出到build/debug/目录。Chrome / Edge 加载打开chrome://extensions禁用已安装的官方 Dark Reader 版本开启开发者模式Developer mode点击加载已解压的扩展程序Load unpacked extension选择项目下build/debug/chrome文件夹。Firefox 加载打开about:addons页面禁用官方版本打开about:debugging#addons点击载入临时附加组件Load Temporary Add-on选择build/debug/firefox/manifest.json文件。若执行npm run debug:watch对应命令见 package.json L14替代npm run debug扩展会在代码改动后自动重新编译适合持续开发仓库还提供debug:watch:mv3Chrome MV3 清单见 package.json L15等变体。规则与建议代码贡献红线超过 10 行的改动请先提交 issue 并讨论方案后再动手保持改动简单尽量少写代码一个 PR 只做一件事拒绝低质量贡献贡献者需确保改动真实可用、解决实际问题禁止 AI 生成代码为主的改动所有评论与沟通必须由真人进行严格禁止新增外部依赖、修改构建流程、改动package.json与package-lock.json可以使用任意编辑器如 Visual Studio Code、WebStorm编辑代码用npm run code-style即npm run lint见 package.json L11自动保持代码风格用npm test即npm run test:unit见 package.json L23运行测试验证改动。从 Dev Tools 到合并的完整贡献闭环把上述内容串成一条可执行的贡献路径定位问题在目标网页上用浏览器元素选择器选中反色异常的元素生成规则在 Dark Reader Dev Tools 中按 Editor Rule 语法编写规则块并Apply分别在明暗模式下验证写回配置文件把验证通过的规则块按 URL 字母序粘贴进 dynamic-theme-fixes.config 或 inversion-fixes.config本已为暗色的整站则加入 dark-sites.config提交 PR提供简短说明 → Propose file change → Create pull request等待校验与合并GitHub Actions 自动运行代码风格校验红叉改、绿勾过维护者 review 后合并修复随下一版本发布。值得注意的是tests/unit/config/config.tests.ts 会真实读取并解析上述三份配置文件readConfig(dark-sites.config)、parseDynamicThemeFixes(...)、parseInversionFixes(...)见 L68、L148-L156、L203-L211从测试层面保证Dev Tools 生成的修复块与仓库解析器之间的格式兼容——这也是为什么严格遵守字母序与命令语法如此重要它不只是规范更是自动化流水线的一部分。【免费下载链接】darkreaderDark Reader Chrome and Firefox extension项目地址: https://gitcode.com/gh_mirrors/da/darkreader创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Dark Reader 贡献指南实战：站点修复规则、Dev Tools 与本地构建调试全解析
Dark Reader 贡献指南实战站点修复规则、Dev Tools 与本地构建调试全解析【免费下载链接】darkreaderDark Reader Chrome and Firefox extension项目地址: https://gitcode.com/gh_mirrors/da/darkreaderDark Reader 是一款开源的浏览器暗色模式扩展MIT 协议任何人都可以通过多种方式为它贡献力量赞助、翻译、提交站点修复规则、报告 Bug 或开发新功能。本文基于仓库根目录的 CONTRIBUTING.md 编写系统讲解Dark Reader 锁协议、dark-sites 与站点修复配置文件的规则语法、Dev Tools 的使用流程以及本地构建调试环境搭建并结合 src/generators/、src/config/ 与 tests/unit/config/config.tests.ts 等源码佐证底层实现帮助贡献者快速上手并提交高质量的 Pull Request。贡献方式总览Dark Reader 的贡献入口非常多样不需要精通 TypeScript 也能参与赞助通过 Open Collective 赞助项目开发帮助维护者投入更多时间维护与开发新功能。翻译改进或新增 src/_locales 目录下的语言文件如zh-CN.config、ja.config等可参考浏览器扩展国际化支持的语言代码表。站点修复向 src/config/dark-sites.config、src/config/dynamic-theme-fixes.config、src/config/inversion-fixes.config 提交规则修正本已为暗色的站点或渲染错误的元素——这是最主流、门槛最低的贡献方式下文将重点展开。功能开发与 Bug 修复先提交 issue 讨论、获得维护者批准后再提交代码。让网站禁用 Dark Readerdarkreader-lock 协议如果你的网站不希望被 Dark Reader 处理例如站点本身已提供暗色模式可以在文档中嵌入一个meta标签作为锁name属性取值为darkreader-lock且必须是head标签的子节点。静态禁用在 HTML 的head中加入head meta namedarkreader-lock /head动态禁用若浏览器已解析出document.head可以用 JavaScript 动态插入锁const lock document.createElement(meta); lock.name darkreader-lock; document.head.appendChild(lock);底层实现原理从源码看锁的检测是实打实的运行逻辑而非文档层面的约定。在 src/inject/dynamic-theme/index.ts 中isDRLocked()L556-L558通过document.querySelector(meta[namedarkreader-lock])判断是否存在锁addMetaListener()L539-L547注册一个MutationObserver监听document.head的子节点变化一旦发现darkreader-lock标签出现立即断开观察器并调用removeDynamicTheme()卸载整个暗色主题在 L541-L545 中锁出现后动态主题会被整体移除这也解释了为什么动态插入锁同样有效——MutationObserver 会捕获到 DOM 变化。仓库还利用同一机制防止多个暗色插件互相冲突interceptOldScript()L577-L595会临时注入一个darkreader-lock标签以接管页面随后在微任务中移除并继续自身逻辑。提交本已为暗色的站点dark-sites.config如果某个网站默认就是暗色主题Dark Reader 不应再对它应用暗色滤镜否则会出现越滤越亮的异常此时应将其加入 src/config/dark-sites.config。提交前必须满足以下条件整个网站含所有子页面默认即为暗色且与系统偏好色系无关URL 必须是真实地址不允许任何形式的跳转/重定向网站必须完整上线处于设计、开发阶段或含即将上线搬迁中等占位内容的不予接受。该文件为纯文本列表每行一个站点域名必须保持字母序如0bin.net、12bytes.org等见 dark-sites.config 第 25 行起。该文件同样支持*.xxx.com形式的通配域名条目见 L1-L24。测试 tests/unit/config/config.tests.ts 会读取该文件并校验格式与排序。修复错误反色三份站点修复配置文件如果页面中某些元素没有被正确反色或样式异常需要按渲染模式选择对应的修复文件渲染模式修复文件Dynamic动态模式src/config/dynamic-theme-fixes.configFilter / Filter滤镜模式src/config/inversion-fixes.config提交时请注意保持按 URL 字母序排列、选择尽量短的选择器、维持文件现有代码风格。使用 Dark Reader Dev Tools 生成修复Dark Reader 内置了开发者工具可直接在真实网页上试验规则并即时预览适合修复暗底上的暗图标过亮背景透明图片缺少白色背景等小问题。典型场景Dynamic 模式页面出现半暗半亮属异常可能需要微调单个元素或容器Filter 模式常见做法是把页面上原本就是暗色的元素反转回来。逐步操作流程打开浏览器开发者工具Chrome 按F12Firefox 打开 InspectorCtrlShiftC点击左上角的元素选择器Firefox 默认启用选中一个反色异常的元素为该元素或同类元素挑选合适的 CSS 选择器例如元素带classicon small时可用.icon点击浏览器工具栏的 Dark Reader 图标打开弹窗切换到More标签点击底部的⛭ All settings按钮在左侧切换到Advanced分区点击底部的️ Dev tools按钮可选切到底部的Per Site Editor标签输入要更新或新增的域名按下一节的规则语法编辑/新增包含 URL 与选择器的规则块点击Apply分别在Light与Dark两种模式下检查页面效果修复生效后打开 dynamic-theme-fixes.config 或 inversion-fixes.config点击Edit需登录 GitHub把 Dev Tools 中的修复块按 URL 字母序粘贴进去填写简短的修改说明点击Propose file change→ 检查改动 →Create pull request。提交 PR 后GitHub Actions 会在后台自动运行代码风格校验几分钟内完成出现红叉时点击Details查看错误并修改 PR出现绿勾表示校验通过随后由 Dark Reader 维护者 review 并合并你的修复将随新版本推送给所有用户。Editor Rule 语法详解Dynamic 模式规则块dynamic-theme-fixes.configdynamic-theme-fixes.config example.com INVERT .icon CSS .wrong-element-colors { background-color: ${white} !important; color: ${black} !important; } IGNORE INLINE STYLE .color-picker IGNORE IMAGE ANALYSIS .logo规则块由域名头与分隔线之间加若干规则命令组成各命令的语义与使用要点如下规则说明备注 / 示例INVERT反转指定元素Dynamic 模式下仅用于暗色背景上不可见的暗色图片Filter 模式下用于反转页面上本就是暗色的元素如图片、视频CSS向页面注入自定义 CSS每条属性必须加!important防止被其他样式表覆盖Dynamic 模式支持${COLOR}模板COLOR为反色前的颜色值例如${white}在暗色模式下会变成${black}IGNORE INLINE STYLE跳过对匹配元素内联样式的分析例p stylecolor: red的style属性将不再被修改IGNORE IMAGE ANALYSIS禁止对匹配选择器的背景图片做图像分析—从源码看这些命令并非文本约定而是有真实的解析实现dynamic-theme-fixes.config由 src/generators/dynamic-theme.ts 中的parseDynamicThemeFixes()L21-L32解析命令到字段的映射定义在dynamicThemeFixesCommandsL13-L19中除上文四种外还支持IGNORE CSS URL忽略指定 CSS 文件中的样式。解析结果会进入DynamicThemeFix类型见 src/definitions.d.ts供生成器使用。该文件当前已有超过 4 万行修复规则如全局*块的 Google 翻译气泡、vimvixen-hint提示条等见 dynamic-theme-fixes.config 第 1 行起贡献时请善用 Dev Tools 而非手写长选择器。URL 头书写规则以域名开头如example.com省略www前缀若修复只针对特定子域应写完整子域如sub.domain.com站点在不同地区使用不同顶级域时可用通配如example.*同一修复适用于多个域名/子域时可分行列出最流行的域名放在第一行example.com sub.example.com example.mirror.com通配符*属于最后手段应尽量避免使用。动态变量Dynamic Variables为背景色或文字色做修复时不要硬编码颜色如#fff、#000、black、white而应使用基于用户设置动态生成的 CSS 变量dynamic-theme-fixes.config example.com CSS .logo { background-color: var(--darkreader-neutral-background) !important; } .footer p { color: var(--darkreader-neutral-text) !important; }可用变量完整列表变量说明适用场景--darkreader-neutral-background与用户设置对应的中性背景色主要用于背景色错误的元素--darkreader-neutral-text与用户设置对应的中性文字色用于文字颜色错误的元素--darkreader-selection-background用户设置的背景色即用户 UI 中的 Background Color 设置--darkreader-selection-text用户设置的文字色即用户 UI 中的 Text Color 设置在仓库的修复规则中这些变量被大量使用例如div.mermaid-viewer-control-panel .btn同时使用--darkreader-neutral-background与--darkreader-neutral-text见 dynamic-theme-fixes.config L66-L69可作参考。Filter / Filter 模式修复inversion-fixes.configinversion-fixes.config example.com INVERT .icon .button #player NO INVERT #player * REMOVE BG .bg-photo CSS .overlay { background: rgba(255, 255, 255, 0.5); }要点Filter 模式的工作原理是整体反转整张页面再把不需要反转的元素图片、视频等通过INVERT段反转回来若某个已反转元素内含有显示异常的内容如图片用NO INVERT规则排除REMOVE BG会移除元素的背景图片并强制使用黑色背景CSS规则与 Dynamic 模式类似Filter 模式不支持${COLOR}模板。底层解析同样有源码依据parseInversionFixes()位于 src/generators/css-filter.tsL219-L225 定义了INVERT/NO INVERT/REMOVE BG与CSS等命令映射。inversion-fixes.config的全局*块见 inversion-fixes.config 第 1 行起默认对img、video、object、svg image及各类内联背景图执行INVERT并在NO INVERT中排除input等元素。添加新功能或修复 Bug流程约定若要新增功能或修复 Bug请先在 GitHub 提交 issue若尚不存在与活跃贡献者讨论并等待批准再动手实现。本地构建与调试以 Node.js 环境为例安装 Node.jsLTS 版本在项目根目录执行npm install安装开发依赖执行npm run debug构建调试版本。package.json中debug对应的命令为node --max-old-space-size3072 tasks/cli.js build --debug见 package.json L13构建产物输出到build/debug/目录。Chrome / Edge 加载打开chrome://extensions禁用已安装的官方 Dark Reader 版本开启开发者模式Developer mode点击加载已解压的扩展程序Load unpacked extension选择项目下build/debug/chrome文件夹。Firefox 加载打开about:addons页面禁用官方版本打开about:debugging#addons点击载入临时附加组件Load Temporary Add-on选择build/debug/firefox/manifest.json文件。若执行npm run debug:watch对应命令见 package.json L14替代npm run debug扩展会在代码改动后自动重新编译适合持续开发仓库还提供debug:watch:mv3Chrome MV3 清单见 package.json L15等变体。规则与建议代码贡献红线超过 10 行的改动请先提交 issue 并讨论方案后再动手保持改动简单尽量少写代码一个 PR 只做一件事拒绝低质量贡献贡献者需确保改动真实可用、解决实际问题禁止 AI 生成代码为主的改动所有评论与沟通必须由真人进行严格禁止新增外部依赖、修改构建流程、改动package.json与package-lock.json可以使用任意编辑器如 Visual Studio Code、WebStorm编辑代码用npm run code-style即npm run lint见 package.json L11自动保持代码风格用npm test即npm run test:unit见 package.json L23运行测试验证改动。从 Dev Tools 到合并的完整贡献闭环把上述内容串成一条可执行的贡献路径定位问题在目标网页上用浏览器元素选择器选中反色异常的元素生成规则在 Dark Reader Dev Tools 中按 Editor Rule 语法编写规则块并Apply分别在明暗模式下验证写回配置文件把验证通过的规则块按 URL 字母序粘贴进 dynamic-theme-fixes.config 或 inversion-fixes.config本已为暗色的整站则加入 dark-sites.config提交 PR提供简短说明 → Propose file change → Create pull request等待校验与合并GitHub Actions 自动运行代码风格校验红叉改、绿勾过维护者 review 后合并修复随下一版本发布。值得注意的是tests/unit/config/config.tests.ts 会真实读取并解析上述三份配置文件readConfig(dark-sites.config)、parseDynamicThemeFixes(...)、parseInversionFixes(...)见 L68、L148-L156、L203-L211从测试层面保证Dev Tools 生成的修复块与仓库解析器之间的格式兼容——这也是为什么严格遵守字母序与命令语法如此重要它不只是规范更是自动化流水线的一部分。【免费下载链接】darkreaderDark Reader Chrome and Firefox extension项目地址: https://gitcode.com/gh_mirrors/da/darkreader创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考