• 文档
• 教程

本篇指南围绕当前仓库中的项目创意 Chrome-Theme-Extension.md 展开：你将学会如何从零构建一款可个性化配色、可一键安装为浏览器默认主题的 Chrome 主题扩展，并实现"夜间自动开启"的蓝光滤镜护眼功能。读完本文，你既能理解 Chrome 扩展在底层是如何加载与生效的，也能掌握 manifest.json 中 theme 配置的完整结构、色盲友好的配色设计思路，以及发布到 Chrome Web Store 的完整流程。

项目定位：为什么这是一个 2-Intermediate 项目

在 app-ideas 仓库中，每个项目都被划分进三个层级，README.md 对第二层级的开发者画像描述是："对 UI/UX、开发工具以及基于 API 服务的应用构建已经比较熟练"。本项目被归入 2-Intermediate，原因在于它同时涉及三块彼此独立的知识：

• Chrome 扩展的运行机制：扩展如何被浏览器识别、加载并生效（即原文档第 7 行要求理解的"Chrome 扩展背后如何工作"）；
• 主题配置结构：Chrome 主题不是用 JS 写出来的界面，而是 manifest.json 中一段声明式的 JSON 配置；
• 前端三件套基础：原文档第 8 行明确要求具备 "HTML/CSS、JS、JSON 的基本理解"，因为夜间模式的定时逻辑与手动开关仍然需要少量 JavaScript 支撑。

原文档给出的核心目标很清晰（第 5 行）：构建一个可自定义颜色的 Chrome 主题扩展，并可选地加入"夜灯（蓝光滤镜）"功能——在夜间自动开启，让长时间写代码或刷剧的用户眼睛不那么疲劳。

Chrome 扩展的工作原理（Behind the Scenes）

要写好一个主题扩展，先要弄清扩展在浏览器里到底是怎么"活"起来的。Chrome 扩展本质上是一个包含manifest.json清单文件（扩展的"身份证"）的文件夹，浏览器依据该清单决定：

1. 加载什么：清单里声明了扩展名称、版本、权限（permissions）、图标等元信息；
2. 运行什么：清单里的background、content_scripts、action（旧版称browser_action/page_action）、options_page字段分别对应后台脚本、注入网页的内容脚本、工具栏按钮弹窗、设置页等能力；
3. 改变什么外观：当清单中出现theme字段时，Chrome 会把扩展识别为"主题扩展"，直接按照其中的颜色、图片、色调（tints）配置重绘浏览器 chrome（即浏览器自身的窗口、工具栏、标签页等界面元素）。

主题扩展与普通扩展最大的区别在于：它几乎不需要任何 JavaScript，核心工作就是把theme字段下的 JSON 配好。你可以同时利用其他能力（比如options_page提供设置页、action提供手动开关按钮）来补足"夜间自动切换"这类动态需求——这正是本项目用户故事与 Bonus 特性落地的技术基础。

用户故事拆解与验收目标

原文档给出了 3 条用户故事与 3 条 Bonus 特性（第 10–20 行），它们是整个项目的验收底线。在动手前，建议把它们翻译成可测试的验收点：

动手实现：manifest.json 与主题定义结构

主题扩展的第一步是创建项目目录并编写manifest.json。以本项目为例，一个最小可用的清单文件大致如下：

{ "manifest_version": 3, "name": "My Night-Friendly Theme", "version": "1.0.0", "description": "A customizable Chrome theme with automatic night light filter.", "icons": { "16": "icons/icon16.png", "48": "icons/icon48.png", "128": "icons/icon128.png" }, "theme": { "colors": { "frame": "#1a1a2e", "toolbar": "#16213e", "tab_text": "#eaeaea", "tab_background_text": "#8f8f8f", "background_tab": "#0f3460", "bookmark_text": "#eaeaea", "ntp_background": "#0f3460", "ntp_text": "#eaeaea" }, "images": { "theme_frame": "images/header.png", "ntp_background": "images/ntp_bg.png" }, "properties": { "ntp_background_alignment": "bottom", "ntp_background_repeat": "no-repeat", "ntp_logo_alternate": 0 }, "tints": { "frame": [-1, -1, -1], "background_tab": [-1, -1, -1], "toolbar": [0.12, 0.4, 0.5] } } }

下面把theme对象的三块配置逐项说明清楚（字段名以当前 Chrome 官方文档为准，个别字段在不同 Chromium 版本中可能被调整或弃用）：

colors：颜色键

colors是一个"颜色键名 → 十六进制色值"的映射，常见键包括：

注意：toolbar_button_icon、toolbar_text、button_background等旧颜色键在较新的 Chromium 中已被标记为废弃，建议以官方 manifest 文档为准，避免发布审核时被拒绝。

images：背景图

images用于给窗口、标签栏、新标签页铺设背景图片，路径相对于扩展根目录。常用键：

• theme_frame：窗口顶部框架背景图；
• theme_toolbar：工具栏背景图；
• ntp_background：新标签页背景图。

如果希望纯色方案（本项目的"个性化颜色"需求通常以纯色为主），可以完全省略images，仅靠colors完成。

properties：行为属性

properties控制图片与徽标的摆放方式：

• ntp_background_alignment：新标签页背景图的对齐方式，常用值如top、bottom、left、right、center；
• ntp_background_repeat：背景图是否平铺，常用no-repeat、repeat-x、repeat-y、repeat；
• ntp_logo_alternate：取0或1，用于切换新标签页的 Chrome 徽标配色，适配深色背景。

tints：色调叠加

tints是三个形如[R, G, B]的浮点数组，取值通常在-1到1之间，表示对该区域颜色施加的色调偏移；[-1, -1, -1]表示"不施加任何修改"。可用键包括frame、background_tab、toolbar。例如"toolbar": [0.12, 0.4, 0.5]会为工具栏叠加一层偏橙的暖色调——这正是后面"蓝光滤镜"降低蓝色通道的底层手段之一。

个性化配色与色盲友好的设计实践

原文档第 12–13 行把"按个人颜色偏好制作主题"和"对色盲人群有益"并列为核心故事，两者并不冲突，关键在设计流程：

1. 提供配色入口：最简单的方式是提供一个options_page（设置页），放置若干个<input type="color">颜色选择器，分别对应frame、toolbar、ntp_background等颜色键，将选中的十六进制值实时预览并同步到主题配置预览图（可用一个 mockup 页面模拟浏览器窗口效果）。
2. 内置可辨识调色板：为色盲用户准备 3–4 套经过验证的预设方案。设计时遵循两个原则——不依赖色相区分（避免仅用红/绿传达信息），保证前景与背景的亮度对比度足够（例如浅色文字#eaeaea配深色背景#0f3460，对比度明显优于灰色系搭配）。
3. 边界情况：给设置页加上"重置为默认"按钮，避免用户改坏颜色后无法恢复。

这段 UI 逻辑只需基础的 HTML/CSS 与少量 JS 监听事件即可完成，恰好落在原文档要求的技能范围内。

夜间模式与蓝光滤镜：核心功能与实现思路

本项目最吸引人的部分是"夜灯（蓝光滤镜）"。蓝光（短波高能可见光）在夜间长时间暴露被认为更容易造成视疲劳，因此护眼方案通常的做法是降低画面中的蓝色通道、让整体色调偏暖。在本项目语境下，"自动开启"需要解决两个子问题：

子问题一：如何判定"夜间"

在options_page或background脚本中用new Date()读取本地时间即可：

function isNight(hour) { // 22:00 ~ 次日 06:00 视为夜间，可按用户偏好调整 return hour >= 22 || hour < 6; } function applyAutoMode() { const hour = new Date().getHours(); chrome.storage.local.set({ nightMode: isNight(hour) }); }

配合chrome.alarms（普通扩展可申请"alarms"权限）每小时触发一次检测，就能实现"夜间自动切换"的效果。需要说明的是：Chrome 没有公开的可编程直接切换主题的 API，主题外观在静态层面由清单决定，因此"自动切换"落地通常有两种务实路线：

• 双主题方案：同时打包日间/夜间两套theme配置，通过chrome.management.setEnabled在停用与启用之间切换，或用设置页引导用户一键切换；
• 色调补偿方案：保留一个偏暖的基础主题（tints中降低蓝色通道，如[0.05, 0.1, -0.15]这类温和取值），夜间模式即作为该主题的默认形态，日间再提供冷色备选。

无论选哪条路，"蓝光滤镜"本质上都是把frame、toolbar、ntp_background等主色向橙/琥珀色系偏移，同时用tints削弱蓝色通道。这也是原文档 Example projects 中提到的 Night Shift（BlueLight Filter）类扩展的核心思路——不过这里只做知识层面的类比，实现细节请以官方主题文档为准。

子问题二：手动开关（Bonus）

原文档第 19 行要求 Bonus 特性"添加一个控制夜视功能的手动切换按钮"。实现上可以给action（工具栏按钮）配一个 popup 弹窗：

<!-- popup.html --> <label><input type="checkbox" id="nightToggle" /> 夜间模式</label> <script src="popup.js"></script>

// popup.js const toggle = document.getElementById('nightToggle'); chrome.storage.local.get('nightMode', ({ nightMode }) => { toggle.checked = nightMode === true; }); toggle.addEventListener('change', () => { chrome.storage.local.set({ nightMode: toggle.checked }); });

手动开关的优先级应高于自动定时：用户一旦手动指定，就应暂停isNight()的自动覆盖，直到用户恢复"自动"选项——这是护眼类扩展的常见交互约定。

安装、设置为默认主题与发布

本地加载与设为默认主题

对应原文档第 14 行的用户故事"安装并设置为默认主题"：

1. 打开 Chrome，地址栏进入chrome://extensions；
2. 打开右上角"开发者模式"开关；
3. 点击"加载已解压的扩展程序"，选择包含manifest.json的项目目录；
4. 主题会立即生效，浏览器外观随配置变化；前往设置 → 外观，可以看到该主题已被列为"当前主题"，用户可随时点击"重置为默认"恢复系统外观。

本地迭代的流程就是"改 JSON → 在扩展详情页点击刷新图标 → 查看效果"，反馈非常直接。

打包上传到 Chrome Web Store（Bonus）

对应原文档第 18 行：

1. 在扩展详情页点击"打包扩展程序"，对项目目录进行打包生成.crx与.pem私钥文件（.pem必须妥善保存，后续更新版本需要同一密钥）；
2. 注册 Chrome Web Store 开发者账号（一次性注册费）；
3. 在开发者控制台上传包含manifest.json、图标与截图的 zip 包，填写商店描述、类别与截图；
4. 提交审核，通过后即可在商店中安装，进入"一键安装"模式。

上传前请自查：name、version无冲突，图标资源齐全，没有引用仓库外的远程资源导致审核失败的风险项。

多浏览器扩展（Bonus）

原文档第 20 行要求把主题扩展到多个浏览器。最容易落地的目标是 Firefox：

• Firefox 同样支持在manifest.json中使用theme键（配合manifest_version2），颜色键与 Chrome 高度重合，大部分配置可以直接复用；
• 差异主要在manifest_version、icons尺寸约定与个别字段（如 Firefox 额外的theme_experiment）上，建议按 Firefox 的扩展文档逐项核对。

从工程组织角度，可以让两套浏览器共享同一个 JSON 配置源，构建脚本按目标平台输出对应的manifest.json，这样维护一套配色即可同步发布到多个浏览器。

验收清单与延伸学习

完成实现后，对照以下清单逐项验收（对应原文档 User Stories 与 Bonus features）：

• 用户能通过颜色选择器或直接编辑 JSON 按个人偏好配色，且效果即时可见；
• 内置至少一套面向色盲人群的高对比度、不依赖红绿区分的配色方案；
• 扩展可本地加载、生效，并可被设置为默认主题、可随时还原；
• （Bonus）完成 Chrome Web Store 上传与发布流程；
• （Bonus）工具栏提供夜间模式手动开关，且可覆盖自动定时逻辑；
• （Bonus）同一套主题配置可打包为 Firefox 主题扩展。

原文档在"Useful links and resources"一节给出的官方 Getting Started 指南（Chrome 扩展开发者文档的入门章节）是继续深入的第一手资料；Example projects 中列举的 chrome-developer-edition-dark 与 Night Shift（BlueLight Filter）两款产品，分别可以作为"开发者暗色主题"与"蓝光滤镜交互"的参考样例进行对照学习。本文未附截图，原因是仓库中的 app-ideas.png 与 coderabbit.jpg 均为项目宣传素材，与"Chrome 主题扩展"的技术主题无直接关联，强插图片反而会稀释信息密度。

作为进阶练习，你还可以在此基础上把配色方案导出为可分享的 JSON 文件（支持导入/导出），或者把"夜间自动开启"的时间段做成用户可配置项——这两点都能让这个 2-Intermediate 项目直接逼近真实产品的体验水平。

• 文档
• 教程