vitepress-template

Appearance

ui-crx 浏览器扩展 ​

**本文引用的文件列表** - [[[[[manifest.json]]]]](../file/ui-crx/manifest.json) - [[[[[background.js]]]]](../file/ui-crx/background.js) - [[[[[content.js]]]]](../file/ui-crx/content.js) - [[[[[popup.js]]]]](../file/ui-crx/popup.js) - [[[[[popup.html]]]]](../file/ui-crx/popup.html) - [[[[[options.js]]]]](../file/ui-crx/options.js) - [[[[[options.html]]]]](../file/ui-crx/options.html) - [[[[[utils.js]]]]](../file/ui-crx/utils.js) - [[[[[mock_data.js]]]]](../file/ui-crx/mock-data.js) - [[[[[Dockerfile]]]]](../file/ui-crx/dockerfile)

目录 ​

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 组件详解
  6. 依赖关系分析
  7. 性能与可靠性
  8. 安全与权限管理
  9. 开发与调试指南
  10. 发布与运维
  11. 故障排除
  12. 结论

简介 ​

ui-crx 是一个基于 Chrome Manifest V3 的浏览器扩展，用于在电商运营平台（如生意参谋、达摩盘、万相台、京东商智、抖音罗盘等）自动采集关键指标数据，并通过后台服务进行批量上传与状态展示。扩展采用模块化的架构：后台服务工作线程负责定时采集、队列与上传；内容脚本负责注入页面、模拟用户操作与提取数据；弹窗界面提供登录、配置查看与手动触发同步；选项页支持少量用户级配置；工具模块封装了存储、API、状态映射与时间格式化等通用能力。

项目结构 ​

ui-crx 扩展的核心文件组织如下：

  • 清单文件：定义扩展元信息、权限、入口与资源
  • 背景脚本：后台服务工作线程，负责定时任务、并发控制、状态持久化与徽章显示
  • 内容脚本：注入页面，负责 DOM 操作、指标选择、时间范围切换与数据提取
  • 弹窗界面：HTML + JS，提供登录、仪表盘、缓存查看与手动同步
  • 选项页：HTML + JS，提供少量用户配置项
  • 工具模块：统一的存储、API、状态映射与时间格式化
  • Mock 数据：开发阶段的模拟接口响应
  • Dockerfile：本地静态资源服务（用于本地预览）

图表来源

章节来源

核心组件 ​

  • 清单与权限：声明 MV3、权限、宿主权限、后台入口、动作入口与内容脚本
  • 后台服务工作线程：上下文菜单、消息监听、同步管理器、徽章管理器、登录过期检查
  • 内容脚本：消息监听、上下文菜单数据采集、指标采集流程、DOM 提取与 Toast 展示
  • 弹窗界面：登录态检查、登录（扫码/短信/账号）、配置拉取、手动同步、缓存查看、状态渲染
  • 选项页：上传间隔配置与保存
  • 工具模块：存储封装、API 封装（GET/POST）、状态映射、时间格式化、登录过期检查
  • Mock 数据：登录、配置、同步、错误上报、版本查询的模拟响应

章节来源

架构总览 ​

扩展采用“后台服务工作线程 + 内容脚本 + 弹窗界面”的三段式架构：

  • 后台服务工作线程：常驻，负责定时循环、并发控制、队列与上传、状态持久化与徽章更新
  • 内容脚本：按需注入，负责页面交互与数据提取
  • 弹窗界面：用户交互入口，提供登录、配置查看与手动触发
  • 选项页：少量用户配置项
  • 工具模块：跨模块共享的存储、API、状态映射与时间格式化

图表来源

组件详解 ​

清单与权限（manifest.json） ​

  • Manifest V3：使用 service worker 类型后台脚本
  • 权限：activeTab、downloads、storage、scripting、tabs、contextMenus、cookies
  • 宿主权限：<all_urls>（允许跨站访问）
  • 后台：background.js（模块化）
  • 动作入口：popup.html（弹窗界面）
  • 选项页：options.html
  • 图标与内容脚本：匹配所有 URL，在 document_idle 注入 content.js

章节来源

后台服务工作线程（background.js） ​

职责与流程：

  • 上下文菜单初始化与点击处理：转发到对应标签页的消息以采集“临时数据”
  • 运行时消息监听：处理同步启动、临时数据上传、缓存队列查询、退出登录、强制重置
  • 登出清理：停止同步、移除认证/配置/同步状态、清空徽章
  • 同步管理器（SyncManager）：
    • 周期性循环：读取配置与认证，逐渠道处理指标
    • 登录检查：根据平台域名检测 Cookie 是否存在有效会话
    • 采集策略：按指标类型（实时/归档）与时间间隔判断是否采集
    • 并发控制：限制同时打开的采集标签数量，队列化采集任务
    • 队列与上传：达到阈值或超时触发批量上传，记录上传计数与最后上传时间
    • 状态持久化：将每个渠道的状态写入本地存储，并通知弹窗更新
    • 徽章管理：根据全局状态（错误/同步中/成功）更新徽章文本与颜色
  • 登录过期检查：启动时检查登录时间是否超过 30 天，超期则清空存储

图表来源

章节来源

内容脚本（content.js） ​

职责与流程：

  • 监听来自后台的消息：
    • 临时数据采集：从上下文菜单触发，抓取标题、URL、选区/图片/正文片段
    • 指标数据采集：根据配置选择指标、选择时间范围、等待稳定后提取表格数据
  • DOM 操作与数据提取：
    • 指标选择：查找“指标选择”按钮，打开弹窗，定位目标指标并确认
    • 时间范围：根据 day/yesterday/week/month 映射选择对应按钮
    • 表格提取：优先选择特定类名的表格，提取首行标题与最后一列数值，最多返回 50 条
  • Toast 提示：在页面右上角展示成功/失败/信息提示，自动淡出

图表来源

章节来源

弹窗界面（popup.html + popup.js） ​

职责与流程：

  • 登录态检查：启动时读取本地存储，若存在令牌则进入仪表盘，否则进入登录页
  • 登录方式：
    • 扫码登录：模拟轮询，5 秒后自动登录成功（演示用）
    • 短信登录：输入手机号与验证码，发送验证码按钮倒计时
    • 账号登录：输入用户名/密码
  • 配置拉取：登录成功后调用配置接口，保存到本地存储
  • 仪表盘：
    • 用户信息展示
    • 渠道状态渲染：名称、状态徽章、描述、统计（已缓存/已上传）、手动更新链接
    • 全部更新：触发强制重置并重启同步
    • 查看缓存：向后台请求缓存队列并展示
  • 消息提示：统一的提示容器，成功自动隐藏，错误保留
  • 状态更新：监听后台推送的状态变更并刷新 UI

图表来源

章节来源

选项页（options.html + options.js） ​

职责与流程：

  • 上传间隔设置：数字输入框，保存到本地存储
  • 加载设置：启动时从本地存储读取并回填
  • 保存反馈：保存成功后短暂提示

章节来源

工具模块（utils.js） ​

职责与流程：

  • API 基础地址与端点：登录、配置、同步、临时数据、错误上报、版本查询
  • 渠道名称映射与状态映射：用于 UI 展示
  • 存储封装：get/set/remove/clear
  • API 封装：post/get 支持 Mock 数据开关，支持 Authorization 头
  • 时间格式化：将时间戳格式化为本地时间字符串
  • 登录过期检查：30 天有效期，超期清空存储

章节来源

Mock 数据（mock_data.js） ​

职责与流程：

  • 登录成功/失败响应
  • 配置响应（包含权限、采集间隔、上传阈值、指标清单）
  • 同步/临时数据响应
  • 错误上报与版本查询响应

章节来源

依赖关系分析 ​

  • 模块内聚与耦合：
    • background.js 与 utils.js 高度耦合，依赖其存储与 API 能力
    • content.js 与 utils.js 低耦合，仅依赖状态映射与时间格式化（通过 popup 导入）
    • popup.js 与 utils.js 高度耦合，承担登录、配置拉取、状态渲染与消息提示
    • options.js 与 utils.js 低耦合，仅依赖本地存储键名
  • 外部依赖：
    • Chrome Runtime API：消息传递、存储、标签页、上下文菜单、徽章
    • Fetch API：HTTP 请求（Mock 开关下由 utils.js 内部处理）
  • 可能的循环依赖：未发现直接循环，但 background.js 与 utils.js 在导入导出上保持单向依赖

图表来源

性能与可靠性 ​

  • 并发控制：限制同时打开的采集标签数量，避免页面卡顿与反爬检测
  • 抖动与节流：采集前随机延迟，上传周期与批量阈值可配置
  • 队列与持久化：缓存队列与同步状态持久化，异常中断后可恢复
  • 徽章滚动：长文本状态滚动展示，提升可读性
  • 登录过期：30 天自动清理，避免长期无效状态

章节来源

安全与权限管理 ​

  • 权限最小化：仅申请必要权限（activeTab、downloads、storage、scripting、tabs、contextMenus、cookies）
  • 宿主权限：<all_urls> 用于跨站采集，建议在生产环境按需收紧
  • 认证与过期：本地存储令牌与登录时间，30 天过期自动清理
  • Cookie 检查：针对不同平台检测关键 Cookie，确保会话有效性
  • 跨域通信：通过 runtime.sendMessage 与 runtime.onMessage 实现安全的消息通道

章节来源

开发与调试指南 ​

  • 本地开发：
    • 使用 Chrome 加载未打包扩展，勾选“开发者模式”，点击“加载已解压的扩展程序”
    • 本地静态资源可通过 Dockerfile 中的 Nginx 服务提供（非必需）
  • 调试技巧：
    • 打开后台页面（chrome://extensions → 调试），观察后台服务工作线程日志
    • 在弹窗界面打开开发者工具，查看消息与状态更新
    • 在目标页面打开开发者工具，观察内容脚本注入与 DOM 操作
  • Mock 数据：
    • 通过 utils.js 中的 USE_MOCK_DATA 控制是否启用模拟响应
    • 登录、配置、同步、临时数据、错误上报均有对应 Mock 响应
  • 日志与错误：
    • 后台与内容脚本均输出采集与上传过程中的错误信息
    • 可通过徽章状态快速定位问题（错误/未登录/同步中/成功）

章节来源

发布与运维 ​

  • 打包与分发：
    • 将扩展目录打包为 zip，提交至 Chrome Web Store 或企业内部分发
  • 版本管理：
    • 通过 utils.js 中的版本查询端点与前端提示实现升级引导
  • 运维监控：
    • 错误上报端点可用于收集扩展运行时错误
    • 通过徽章状态与弹窗缓存详情辅助排查

章节来源

故障排除 ​

常见问题与解决思路：

  • 登录失败：检查用户名/密码或验证码；确认 Mock 数据开关与网络可达性
  • 未登录状态：检查 Cookie 检查逻辑与平台会话有效性
  • 同步不生效：确认配置中权限列表与指标清单；检查上传阈值与时间间隔
  • 缓存为空：确认采集是否成功，检查徽章状态与弹窗缓存详情
  • 页面无响应：检查内容脚本注入时机（document_idle）与页面稳定性等待

章节来源

结论 ​

ui-crx 扩展以 MV3 为基础，结合后台服务工作线程、内容脚本与弹窗界面，实现了对多平台电商数据的自动化采集与上传。通过并发控制、队列与持久化、徽章状态与 Mock 数据等机制，提升了可用性与可维护性。建议在生产环境中进一步收紧宿主权限、完善错误上报与监控，并持续优化采集策略与 UI 体验。