JavdBviewed 文档中心

Appearance

二次开发指南 ​

本页面向希望从源码构建、调试、理解或扩展 JavdBviewed 的开发者。相比用户文档，这里更关注代码结构、模块职责、开发流程与排查思路。

建议阅读顺序 ​

  1. 先看 架构说明
  2. 再看本页的开发环境与项目结构
  3. 接着按需阅读 数据同步模块 与 115 模块说明
  4. 涉及 Dashboard 交互时，再看 UI 组件说明

你会在这里解决什么问题 ​

  • 如何把项目跑起来并加载到浏览器里
  • 代码大致分成哪些层，功能应该放在哪里
  • 页面脚本和后台脚本如何通信
  • 数据存放在哪里，同步链路怎么走
  • 新增一个功能时，通常从哪几层下手

开发环境 ​

系统要求 ​

  • Node.js 18 或更高版本
  • npm 9 或更高版本，或使用 pnpm
  • Git
  • 推荐使用 VS Code

克隆项目 ​

bash
git clone https://github.com/JavdBviewed/JavdBviewed.git
cd JavdBviewed

安装依赖 ​

bash
pnpm install

如果你习惯使用 pnpm，也可以自行切换，但请优先确保与当前仓库脚本保持一致。

构建扩展 ​

bash
pnpm run build

构建完成后，产物会输出到 dist/。

加载到浏览器 ​

  1. 打开浏览器扩展管理页面
  2. 开启“开发者模式”
  3. 点击“加载已解压的扩展程序”
  4. 选择仓库中的 dist/ 目录

常见入口：

  • Chrome：chrome://extensions/
  • Edge：edge://extensions/

项目结构 ​

下面是理解项目时最值得先掌握的一层结构，而不是完整文件清单。

text
JavdBviewed/
├── src/
│   ├── background/     # 后台脚本与消息分发
│   ├── content/        # 页面注入脚本与页面增强
│   ├── popup/          # 扩展弹窗
│   ├── dashboard/      # 设置面板与管理页面
│   ├── services/       # 业务服务层
│   ├── components/     # 通用组件
│   ├── utils/          # 工具方法与配置
│   ├── types/          # 类型定义
│   └── assets/         # 静态资源
├── public/             # 扩展静态资源
├── scripts/            # 构建脚本
├── dist/               # 扩展构建产物
└── package.json        # 脚本与依赖定义

模块分层怎么理解 ​

如果你要新增功能，先判断自己改的是哪一层，会省很多时间。

content/：页面侧能力 ​

适合放这些内容：

  • 页面识别与初始化
  • 详情页、列表页增强
  • 按钮、标记、浮层、快捷操作
  • 页面内状态刷新

一句话理解：凡是“直接显示在站点页面上”的，大概率先看这里。

background/：后台中枢 ​

适合放这些内容：

  • 统一消息监听与路由
  • 数据读写
  • 同步任务
  • 外部接口调用
  • 长生命周期任务管理

一句话理解：凡是“需要统一调度、跨页面共享或不该放在页面上下文里”的，大概率放这里。

dashboard/：设置与管理界面 ​

适合放这些内容：

  • 设置项配置
  • 番号库、演员库、任务列表等管理页面
  • 数据展示与复杂交互

一句话理解：凡是“像一个管理后台”的界面逻辑，优先看这里。

services/：业务逻辑封装 ​

适合放这些内容：

  • 演员管理
  • 同步服务
  • 新作品检测
  • 与具体业务强相关、但不属于单一页面的逻辑

一句话理解：当某段逻辑既不应该直接塞进页面，也不适合散落在后台入口里，就应该考虑抽成服务。

核心数据放在哪里 ​

IndexedDB ​

用于存放结构化业务数据，例如：

  • 视频标记记录
  • 演员数据
  • 新作品记录
  • 需要检索、筛选、统计的本地数据

这类数据通常体量更大、结构更稳定、查询需求更多。

Chrome Storage ​

用于存放轻量配置，例如：

  • 用户设置
  • 功能开关
  • 一些浏览器级别的本地配置

如果你不确定该放哪，先想这个数据是不是“业务主数据”。如果是，优先考虑 IndexedDB；如果只是设置项，优先考虑 Chrome Storage。

页面和后台如何通信 ​

项目的一个关键点是：很多功能并不是页面自己单独完成的，而是页面脚本发消息给后台，再由后台执行业务逻辑。

常见流程：

  1. 用户在页面点击某个按钮
  2. content 脚本整理参数
  3. 通过 chrome.runtime.sendMessage 发给后台
  4. background 处理数据库、同步或外部请求
  5. 处理结果回传页面
  6. 页面刷新显示状态

如果你遇到“按钮点了没反应”，通常要同时检查：

  • 页面事件有没有触发
  • 消息有没有发出去
  • 后台有没有收到
  • 后台处理是否报错
  • 回传结果是否正确更新 UI

新增一个功能时的推荐步骤 ​

下面是一条比较稳的路径。

1. 先明确功能归属 ​

先判断：

  • 是页面交互增强？
  • 是后台任务？
  • 是设置面板能力？
  • 是一个跨模块业务服务？

先定位置，再动代码。

2. 先补类型，再写实现 ​

如果功能涉及新数据结构或新消息类型，建议先补：

  • 类型定义
  • 消息类型
  • 配置项类型

这样后面调试成本会更低。

3. 再接消息和存储 ​

如果功能需要后台参与，优先把消息链路跑通：

  • 页面发消息
  • 后台收到并返回
  • 页面能正确处理返回值

消息链路通了，再接数据库、同步或外部 API。

4. 最后补 UI 和设置 ​

把最容易变动的界面层放在后面做，能减少来回返工。

调试建议 ​

页面侧调试 ​

适合排查：

  • 按钮没出现
  • 样式错位
  • 页面状态没刷新
  • 事件没有触发

可直接打开站点页面的 DevTools 查看 Console、Elements、Network。

扩展侧调试 ​

适合排查：

  • 后台消息没处理
  • 数据没写入
  • 同步没触发
  • 外部接口失败

可以在浏览器扩展管理页面打开扩展的检查视图。

常见排查顺序 ​

建议按这个顺序看：

  1. 页面上有没有入口
  2. 点击后页面日志是否正常
  3. 后台是否收到消息
  4. 后台处理是否报错
  5. 数据层是否成功写入
  6. UI 是否根据返回值刷新

构建与发布 ​

本地构建 ​

bash
npm run build

文档站预览 ​

在 JavdBviewed-Docs 仓库根目录执行：

bash
pnpm run dev

文档站构建 ​

bash
pnpm run build

发布建议 ​

  1. 先本地验证关键流程
  2. 再构建扩展产物
  3. 再创建 GitHub Release
  4. 最后上传发布文件并更新说明

常见开发问题 ​

构建失败 ​

优先检查：

  • Node.js 版本是否过低
  • 依赖是否安装完整
  • package.json 脚本是否被改动
  • 是否有 TypeScript 报错

扩展能加载但功能不生效 ​

优先检查：

  • 是否加载了最新的 dist/
  • 内容脚本是否真的注入到目标页面
  • 消息通信是否中断
  • 控制台是否有运行时错误

同步或外部服务异常 ​

优先检查：

  • 配置项是否保存成功
  • 后台日志是否有错误
  • 外部服务本身是否可访问
  • 是否存在登录态、权限或网络问题

延伸阅读 ​

JavdBviewed 文档中心

Copyright © 2026 lmixture