JSON Alexander架构完全解析：5个核心文件与manifest.json如何驱动整个JSON查看器扩展-育师

【免费下载链接】JSON-Alexander

A really good JSON viewer browser Extension

项目地址：https://gitcode.com/gh_mirrors/js/JSON-Alexander

JSON Alexander 是一款浏览器 JSON 查看器扩展，它能自动接管任何返回 JSON 的网页，把枯燥的纯文本变成可折叠、可高亮、可复制路径的交互式 JSON 查看器。整个项目架构极其精简：仅由 manifest.json 和 src/ 目录下的 4 个源码文件（共 5 个核心文件）构成，配合 Vite 构建流水线即可产出 Chrome 与 Firefox 双平台的扩展包。

项目速览：5 个核心文件各司其职

先建立整体印象——这个 JSON 查看器扩展的文件分工如下：

文件	角色
manifest.json	扩展"总开关"，声明注入时机与权限
src/content.ts	内容脚本：检测 JSON、接管页面、构建工具栏
src/viewer.ts	渲染引擎：可折叠 JSON 树、层级折叠、路径悬停
src/page-script.ts	页面脚本：把数据注入`window.data`
src/styles/viewer.css	主题与语法高亮样式

构建配置则由 vite.config.ts 和 package.json 负责，类型约束见 tsconfig.json。

manifest.json：一个 30 行的"总开关"

manifest.json 采用 Chrome 扩展标准的manifest_version: 3架构，全文不到 30 行，却决定了扩展如何"寄生"进每个网页。

核心配置有三个关键点：

content_scripts注入规则：matches设为<all_urls>，意味着打开任何 URL 时，浏览器都会在document_end时机自动注入content.js与content.css——这是 JSON 查看器"自动接管页面"能力的起点
permissions: ["storage"]：只申请了一个storage权限，用于持久化保存主题偏好（dark/light/auto）和自定义指针开关
web_accessible_resources：白名单放行了page-script.js、pointer-32.png和content.css。因为内容脚本运行在隔离世界（isolated world）中，想往页面本身注入脚本就必须先走这个白名单

此外，browser_specific_settings.gecko.id字段为 Firefox 注册了json-alexander@local身份，让同一套代码无需修改即可在 Firefox 中加载。

构建流水线：Vite 双入口产出两个脚本

浏览器扩展有个硬性限制：MV3 的内容脚本不能是 ES Module，必须是 IIFE 格式的经典脚本。vite.config.ts 用ENTRY环境变量解决了这个问题——package.json 的build脚本会执行两次构建：

ENTRY=content：打包src/content.ts（内部会import整个 viewer.ts），产出dist/content.js
ENTRY=page-script：单独打包src/page-script.ts，产出dist/page-script.js

第一次构建还会启用viteStaticCopy插件，把 manifest.json、icons/ 图标和指针图片一起复制进dist/目录。npm run zip一步即可打包出可分发的json-alexander.zip。

content.ts：JSON 检测与页面接管

src/content.ts 是扩展的"大脑"，入口逻辑集中在detectJSON()函数（src/content.ts#L73-L91）：

识别 JSON 页面：判断页面是否是"纯净的 JSON 响应"——要么body下只有一个<pre>标签，要么响应头的 Content-Type 包含json
解析原文：用JSON.parse尝试解析，失败则安静退出，不打扰普通网页
接管页面：确认是 JSON 后，直接清空整个documentElement，重建出工具栏 + 内容区的全新 DOM 结构

工具栏上你能看到的每个按钮，都是在这里用模板字符串一次性生成的：层级按钮（1/2/3…All）、视图切换（Tree / Formatted / Raw）、主题切换、复制 JSON、设置菜单。

主题偏好通过chrome.storage.local读写，key 为jv-theme，在 auto → dark → light 之间循环（src/content.ts#L102-L125）——这就是 manifest 里那唯一一条storage权限的用武之地。

viewer.ts：可折叠 JSON 树的渲染引擎

真正的"查看器"逻辑全部在 src/viewer.ts，它是本扩展最核心的 325 行文件，对外导出 6 个函数：

renderTree：递归遍历 JSON 树，为每个节点生成一行 DOM，并用data-path属性记录该节点的完整 JSON 路径（src/viewer.ts#L158-L170）。每行还会显示节点数量（如8 keys、2 items）和快捷操作按钮
collapseToLevel/expandAll：工具栏层级按钮背后的实现，按data-depth属性批量折叠/展开到指定深度
toggleNode/toggleAllChildren：单击展开/收起单个节点，或一键处理某节点的全部子容器
setupHoverPath：鼠标悬停任意一行，工具栏即刻显示完整 JSON 路径（如data[1].address.city）；点击可固定路径，按Esc解除，再点 Copy 即可复制——这是 JSON 调试时最实用的功能之一

page-script.ts：把数据"送回"页面上下文

内容脚本与页面运行在不同的 JS 世界，直接赋值window.data页面是感知不到的。src/page-script.ts 只有 15 行，解决的就是这最后一步：

content.ts先把原始 JSON 写入一个隐藏的<script id="jv-json-data">标签，再通过chrome.runtime.getURL("page-script.js")动态插入脚本（src/content.ts#L340-L354）
页面脚本在页面上下文中读取该标签，JSON.parse后挂到window.data，并在控制台打印一行提示

之后打开 DevTools，直接在 Console 里就能用data变量做任意调试。这正是web_accessible_resources白名单存在的意义。

viewer.css：双主题与语法高亮

src/styles/viewer.css 用一套 CSS 变量实现了暗色（默认，Catppuccin 风格配色）和亮色两套主题，通过#jv-root上的data-theme属性切换；auto模式则跟随系统。

它还负责了 JSON 查看器最直观的"质感"：key 蓝色、字符串绿色、数字橙色、布尔紫色、null 灰色的语法高亮，以及缩进参考线在悬停时泛黄高亮的效果，帮助你在深层嵌套中快速对齐层级。

彩蛋：来自 George 的"自定义指针"

设置菜单 ⚙ 里还有一个 Custom cursor 开关，开启后指针会变成一只手绘的"毛手"——这是对扩展标语 "Believe it or not, George formats JSON" 的幽默致敬。默认关闭，状态同样存在chrome.storage.local中（src/content.ts#L174-L183）。

总结：一次请求的完整数据流

把这个 JSON 查看器扩展的 5 个核心文件串起来，数据流非常清晰：

浏览器打开 JSON 页面 →manifest.json声明在document_end注入 →content.ts检测并解析 JSON、重建页面 →viewer.ts递归渲染可折叠树 → 用户悬停/点击交互 →viewer.css提供主题与高亮 →page-script.ts将数据注入window.data供控制台使用

架构上没有任何多余环节：一份 manifest、一个内容脚本、一个渲染引擎、一个桥接脚本、一份样式表。如果你想从零构建自己的浏览器 JSON 查看器扩展，这个项目就是最小完整参考实现。