MediaGo 浏览器扩展（Manifest V3）使用与原理指南：跨站视频嗅探、一键导入 Desktop 与 Docker

• 音视频
• 桌面应用
• 后端

本篇指南以 MediaGo 仓库自带的轻量级 Manifest V3 浏览器扩展为对象，完整讲解它的嗅探能力、安装方式、三种调用模式（Desktop Schema 协议 / Desktop HTTP / Docker 自建服务）、导入行为开关与常见故障排查，并结合packages/mediago-extension与packages/browser-extension的源码实现说明其底层工作机制。读完本文，你将能够在 Chrome / Edge 中正确安装并配置该扩展，理解协议调用与 HTTP 调用各自的边界，并能在测试连接失败、批量导入失败等问题出现时快速定位原因。

扩展能做什么：跨站嗅探与页面识别

MediaGo 自带一个随 Desktop 版本一同发布的轻量浏览器扩展，核心能力是"嗅探 + 一键导入"：

• 跨站点嗅探 HLS / m3u8 流，以及直连的.mp4/.flv/.mov等媒体文件；
• 识别特定视频站点页面：Bilibili 视频页、YouTube 视频 / 短片 / 直播 / 嵌入页（此外还覆盖 X（Twitter）、TikTok、抖音、小红书等平台的 URL）；
• 在浏览器工具栏图标上显示当前页面已检测到的资源数量；
• 一键将单条或全部资源导入 MediaGo（Desktop 或自建服务）。

从源码看，嗅探逻辑集中在 背景脚本，它把检测分成两个层级：

1. 请求级检测（request-level）：通过chrome.webRequest.onSendHeaders监听所有标签页的外发请求，用matchRequestUrl(details.url)按路径匹配.m3u8、.mp4等资源；命中后把资源追加到对应标签页的检测列表，并附带页面标题、来源文档 URL 与请求头（formatHeaders把HttpHeader[]拼成换行分隔的name:value文本）。对 m3u8 资源还会进入一个 150ms 去抖的批量检查流程（queueInspection/flushInspections），通过后端/api/sources/inspect接口探测码率与多码率变体信息。
2. 页面级检测（page-level）：监听chrome.tabs.onUpdated，在标签页 URL 落定后调用matchPageUrl识别 Bilibili / YouTube 等站点，此时"检测到的资源"就是页面 URL 本身——真正下载时由 MediaGo 后端的专用提取器（BBDown 之于 Bilibili、yt-dlp 之于 YouTube）负责解析。

扩展针对哪些站点启用页面级功能，由 manifest.config.ts 中的PAGE_ACTION_MATCHES白名单定义（bilibili.com、youtube.com、youtu.be、x.com / twitter.com、tiktok.com、douyin.com、xiaohongshu.com 等），这也是 content script 的注入范围。此外，DEFAULT_SETTINGS中默认开启的pageQuickActionEnabled会在这些站点页面内注入快捷操作按钮（入口见 content/page-action-entry.ts）。

安装：以"加载已解压的扩展程序"方式安装

MediaGo 扩展目前尚未上架 Chrome Web Store，必须通过开发者模式"加载已解压的扩展程序"安装。Desktop 版安装器已经把扩展产物打包进安装目录，无需单独下载。官方步骤：

1. 打开 MediaGo Desktop 应用；
2. 进入设置 → 更多设置 → 浏览器扩展目录，点击按钮打开扩展文件夹；
3. 在 Chrome / Edge 地址栏访问chrome://extensions/；
4. 右上角开启开发者模式；
5. 点击加载已解压的扩展程序，选择第 2 步打开的那个文件夹；
6. 扩展图标出现在工具栏即安装成功，建议点击图钉将其固定。

若你是在开发环境中手动构建扩展，需要先在仓库根目录执行构建命令，产出dist产物后再按上述流程加载：

pnpm -F @mediago/extension build

扩展包的构建脚本定义在 packages/mediago-extension/package.json：build走 Vite +@crxjs/vite-plugin生成 MV3 产物，另附pack（打 zip 包）、verify:build-artifacts（校验构建产物）与lint/type:check等质量门禁。

值得注意的一个设计细节：扩展的version字段直接读取 Desktop 应用版本号（apps/electron/app/package.json），并剥离 SemVer 后缀后写入 manifest 的version，完整版本号则放入version_name（见 manifest.config.ts 的toManifestVersion）。这样chrome://extensions页面显示的版本与 MediaGo 窗口的"当前版本"保持一致，两处版本只维护一份。manifest 同时声明了minimum_chrome_version: "127"、default_locale: "en"，以及webRequest、tabs、storage、cookies权限与<all_urls>主机权限。

三种调用模式：配置与底层机制

安装后点击扩展图标，在弹窗右上角进入齿轮（设置页），在连接卡片中选择一种调用方式。官方文档给出的三种模式对比如下：

扩展不会自动降级。选定模式后，调用失败会直接报错。要换模式请回到设置页手动切换。源码中importSources是一个按settings.mode硬分发的switch，失败时不会尝试其他通道，与文档描述完全一致。

Desktop · Schema 协议

Schema 模式不依赖本地端口，而是通过**自定义协议深链（deeplink）**把任务交给操作系统注册的协议处理器（Electron 主进程）。实现见 mediago-client.ts：

• buildTaskDeeplink构造形如mediago-community://share?v=1&url=…&name=…&type=…的链接（协议名来自MEDIAGO_SCHEME，见下文）；
• openDeeplink通过chrome.tabs.update让当前活跃标签页导航到该协议 URL，Chrome 检测到无对应 Web 资源后，把请求交给系统协议处理器并弹出"Open MediaGo?"对话框。首次勾选"总是允许"之后，后续调用即为静默直通。

协议名并非硬编码：MEDIAGO_SCHEME从import.meta.env.APP_NAME读取，缺省回退到mediago-community，与 Electron 侧注册的 scheme 保持一致（见 shared/constants.ts）。这意味着重新品牌化 Desktop 构建时只需改一处.env，扩展与 Electron 会自动同步。

Desktop · HTTP 本地接口（默认模式）

默认模式是 HTTP 本地接口。扩展固定请求http://127.0.0.1:39719（常量DESKTOP_HTTP_BASE），无需任何配置。注意：

• 39719对应 Electron 主进程中硬编码的preferredPort（见 apps/electron/src/services/downloader.server.ts），是 Desktop 内嵌下载服务专用端口；
• 它与独立部署 Go Core（Web/server 模式）使用的9900端口是两套不同的部署形态，只是恰好共享同一个二进制，排查问题时切勿混淆。

Docker / 自建服务 · HTTP

连接远端自建 MediaGo 服务端时，需要在设置页填写服务器 URL；若后端以--enable-auth启动，则还需填写 API Key。写入前设置页会对输入做归一化处理：URL 去除尾部斜杠、API Key 去除首尾空白（见 settings-model.ts 的normalizeConnectionDraft），并校验 Docker 模式下 URL 必填。请求时 API Key 通过X-API-Key请求头发送（withApiKey），同时携带Accept-Language头以匹配扩展所选语言。

测试连接做了什么

设置页的"测试连接"按钮底层调用probe：

• HTTP 模式：GET /healthy，1.5 秒超时，任何 2xx 即视为可达（probeHttp）；弹窗和扩展图标状态徽标都复用该探测结果；
• Schema 模式：因为无法静默探测系统协议处理器，测试会直接打开mediago-community://open深链——若系统里没有注册处理器，Chrome 会显示标准的不支持协议提示（probeSchemaPing）。

导入行为：两个开关的语义

设置页导入行为卡片包含两个开关：

• 立即开始下载：开 = 任务进队列并立刻开跑；关 = 仅加入下载列表，等用户手动触发。对 Schema 和 HTTP 两种模式都生效。HTTP 导入时该开关映射为POST /api/downloads请求体中的startDownload字段（importViaHttp组装{ tasks, startDownload }），任务字段包含名称、URL、类型、请求头与空文件夹字段（sourcesToTasks）。
• 静默导入（Schema 模式）：开 = Schema 调用携带静默标记（文档描述为silent=1），MediaGo 收到即创建任务；关 = MediaGo 会弹出下载表单让你核对名字 / 类型 / 保存路径再提交。仅 Schema 模式生效，HTTP 模式一律静默。当前仓库中buildTaskDeeplink构造的深链携带v、url、name、type四个参数，解析与静默判定由 Electron 主进程完成。

设置项本身持久化在chrome.storage.local的mediago.settings键下（见 storage.ts），默认值为desktop-http模式、downloadNow: false——即首次安装默认只入列不自动开跑，把控制权交给用户。检测到的资源则存放在chrome.storage.session的mediago.tab.<tabId>键中，关闭标签页或重启浏览器即清空，避免残留过期数据。

界面语言

扩展支持中文、英文和意大利语，默认跟随浏览器 UI 语言。manifest 以default_locale: "en"兜底，chrome://extensions页面、工具栏提示等扩展无法直接控制的界面文案通过public/_locales/<lang>/messages.json按浏览器语言解析；弹窗与设置页内部的 UI 则用 i18next 单独翻译，因此你可以在设置页界面语言卡片强制覆盖为"跟随系统 / 中文 / English / Italiano"之一。语言解析逻辑见 i18n/language.ts，设置保存时同样会通过resolveLanguage归一化为en/zh/it三者之一。

常见问题排查

点"浏览器扩展目录"打不开

• 开发场景：先跑pnpm -F @mediago/extension build构建扩展产物，再回到 Desktop 设置页打开目录；
• 生产场景：重新安装 MediaGo，确保resources/extension/存在于应用安装目录中。

Desktop · HTTP 模式测试连接失败

• 确认 MediaGo Desktop 正在运行；
• 确认端口39719没被其他进程占用（Windows 下可执行netstat -ano | findstr 39719）；
• 如果你本地同时跑了 Web/server 模式的 Go Core，注意那个用的是9900，不是39719——两者端口不同、部署形态不同。

Schema 模式每次都弹窗

首次唤起"Open MediaGo?"（或 "Open MediaGo-community?"）对话框时，勾选总是允许即可。之后 Chrome 会把请求静默转给 Desktop，不再询问。因为深链依赖系统协议处理器，任何会重置该允许记录的操作（如重装浏览器、清理站点数据）都可能导致弹窗重现。

批量导入 Schema 模式失败

这是协议调用的固有边界：chrome.tabs.update只能让当前标签页导航到单个协议 URL，无法安全地串联多次调用，因此 Schema 模式一次只能发送一条任务。源码中importViaSchema对sources.length > 1直接返回"批量导入不支持"的本地化错误，而不是静默丢弃任务。要批量导入请切换到 HTTP 模式（Desktop 或 Docker 均可）。另外，带请求头的资源（如需要鉴权 cookie 的流媒体）也无法走 Schema 深链（深链无法承载请求头），同样需要改用 HTTP 模式。

进一步探索源码

如果你想深入了解扩展的实现细节，建议从以下文件入手：

• 扩展整体工程：packages/mediago-extension（manifest、popup、options、background、content 五大部分）
• 嗅探与标签页生命周期：packages/mediago-extension/src/background/sniffer.ts
• 模式分发与协议/HTTP 调用：packages/mediago-extension/src/background/mediago-client.ts
• 站点适配器（Bilibili / YouTube / 短视频 / Twitter / 小红书）：packages/browser-extension/src/site-adapters
• 嗅探规则与公共常量：packages/common/src

各模块均配有较完整的单元测试（如 sniffer.test.ts、mediago-client.test.ts、manifest-config.test.ts），测试用例本身也是理解行为边界的好材料。

• 音视频
• 桌面应用
• 后端