如何用Manifest V3开发一个实用浏览器扩展ff2mpv架构设计完整剖析【免费下载链接】ff2mpvA Firefox/Chrome add-on for playing URLs in mpv.项目地址: https://gitcode.com/gh_mirrors/ff/ff2mpvff2mpv 是一个基于Manifest V3开发的轻量级浏览器扩展支持 Firefox、Chrome 及所有基于 Chromium 的浏览器。它的功能非常直接点击工具栏图标就能把当前网页链接交给本地的mpv 播放器打开播放右键页面上的链接、图片或视频同样可以一键Play in MPV。正因功能极简ff2mpv 成为学习 Manifest V3 扩展架构的绝佳样本——它的整个核心逻辑不到 300 行代码却完整覆盖了 MV3 开发中的四大核心机制manifest.json配置、Service Worker 后台脚本、Native Messaging 本地通信、Storage API 配置持久化。本文将以 ff2mpv 为例带你完整剖析一个实用浏览器扩展的架构设计。一、先认识 ff2mpv功能与使用方式ff2mpv 提供两种使用方式操作效果点击工具栏小图标将当前标签页 URL发送给 mpv 播放右键链接 / 图片 / 视频 / 选中文本在上下文菜单中选择Play in MPV播放它还有一个进阶功能——配置档案Profile你可以在选项页为不同场景保存一组 mpv 启动参数例如硬件加速、音频输出设备然后在右键菜单中按档案播放。扩展本身只负责传 URL真正的播放由你电脑上的 mpv 完成这也是后文要讲的 Native Messaging 架构的价值所在。二、项目文件结构MV3 扩展的最小骨架ff2mpv 的文件组成非常精简这也是 MV3 扩展推荐的组织方式文件/目录作用manifest.json扩展的身份证声明版本、权限、入口ff2mpv.js后台 Service Worker处理所有事件与消息ff2mpv.py原生消息宿主Native Host负责拉起 mpvoptions/options.html选项页界面管理播放参数档案options/options.js选项页逻辑读写 storage 并同步菜单ff2mpv.json / ff2mpv-chromium.json / ff2mpv-windows.json各浏览器的原生宿主注册清单install.sh / install.ps1Linux/macOS 与 Windows 的宿主安装脚本package-firefox.sh / package-chromium.sh打包发布脚本dist.files打包清单定义扩展包含哪些文件架构一图流文字版工具栏图标 / 右键菜单 │ ▼ ff2mpv.jsService Worker── 收集 URL 与参数 │ sendNativeMessage ▼ ff2mpv.pyNative Hoststdio 协议 │ Popen ▼ mpv 播放选项页则通过chrome.runtime.sendMessage与 Service Worker 通信把档案数据写入chrome.storage.sync。三、manifest.json 深度解析MV3 的 5 个关键配置manifest.json 是整个扩展的起点。ff2mpv 的清单里有 5 个值得新手重点学习的配置1. 双浏览器兼容的 background 声明background: { scripts: [ff2mpv.js], service_worker: ff2mpv.js }这是 MV3 开发的经典技巧service_worker是 Chrome 的 MV3 标准写法而旧版 Firefox 仍通过scripts加载。同时写两个键一份后台代码即可同时服务两大引擎。2. 用 action 替代 V2 的 browser_actionMV3 中工具栏图标由action字段声明ff2mpv 还通过commands中的_execute_action为图标操作提供了快捷键绑定。3. 权限最小化原则ff2mpv 申请了 5 个权限每个都有明确用途权限用途nativeMessaging与本地 Native Host 通信contextMenus创建右键菜单activeTab仅在用户点击时才获取当前标签页 URL比tabs更克制storage保存播放参数档案scripting播放前注入脚本暂停页面内的 HTML5 视频新手建议权限是扩展商店审核的重灾区能申请activeTab就不要申请tabs。4. options_ui在侧边栏打开选项页options_ui: { page: options/options.html, open_in_tab: false }open_in_tab: false让选项页以弹出面板形式打开交互体验更轻快。5. 浏览器身份声明browser_specific_settings.gecko.id为 Firefox 侧注册了ff2mpvyossarian.net这个唯一 ID——这是后续 Native Host 做来源白名单校验的前提。四、Service Worker 后台脚本事件驱动的消息中枢ff2mpv.js 是扩展的大脑。MV3 的 Service Worker 没有常驻 DOM、生命周期短暂所以它的设计哲学是一切皆事件。ff2mpv 注册了 5 类监听器构成完整的事件中枢️chrome.action.onClicked点击图标时直接取tab.url发给 Native Hostchrome.contextMenus.onClicked右键菜单点击时按优先级从info.linkUrl→srcUrl→selectionText→frameUrl中提取目标 URLchrome.runtime.onInstalled安装/更新后按已有档案重建右键菜单单条目或Profiles子菜单chrome.runtime.onMessage接收选项页的创建/更新/删除档案消息动态增删右键菜单项chrome.runtime.onMessageExternal接收外部应用如桌面工具发来的openVideo请求。其中有个 MV3 细节值得注意contextMenus.create仍是回调风格 APIff2mpv 用一个十几行的 Promise 包装器统一了 API 风格并检查chrome.runtime.lastError——在 MV3 中忽略 lastError 是新手最常见的坑。另外一个小而优雅的设计发起播放前它先用chrome.scripting.executeScript注入一段脚本暂停页面内所有video避免网页视频和 mpv 同时出声。五、Native Messaging打通浏览器与本地 mpv 的桥梁这是 ff2mpv 架构中最精彩的部分也是多数教程不会讲的进阶内容。1. 原理stdio 协议浏览器无法直接启动本地程序MV3 提供了 Native Messaging 机制扩展把消息发给一个原生宿主Native Host宿主从 stdin 读取、向 stdout 回复。ff2mpv.py 用不到 70 行 Python 实现了这个协议核心是4 字节消息长度 JSON 消息体的帧格式# 读取4 字节长度头 JSON length struct.unpack(I, sys.stdin.buffer.read(4))[0] message sys.stdin.buffer.read(length).decode(utf-8)收到{url: ..., options: [...]}后它组装命令行mpv --no-terminal options -- url并用subprocess.Popen启动最后回一句ok——必须回复否则浏览器控制台会报 An unexpected error occurred。代码里还藏着两个跨平台工程经验Windows 上需要CREATE_BREAKAWAY_FROM_JOB防止进程被任务管理器连带杀掉macOS 上图形应用的 PATH 继承自launchd看不到 Homebrew 安装的 mpv因此手动补了/opt/homebrew/bin到 PATH。这些坑在 README 和源码注释中都有记录是新手学习跨平台扩展开发的最佳实践素材。2. 宿主注册清单白名单安全机制Native Host 不是随便谁都能调用的必须注册 JSON 清单到浏览器指定目录且通过白名单校验来源Firefox 系ff2mpv.json用allowed_extensions校验扩展 IDChromium 系ff2mpv-chromium.json用allowed_origins校验扩展的 origin 地址Windowsff2mpv-windows.json宿主程序指向批处理脚本 ff2mpv.bat内部调用python ff2mpv.py。三套清单对应不同的注册位置浏览器配置目录下的NativeMessagingHosts/native-messaging-hostsWindows 则在注册表这正是项目里存在三个 JSON 文件的原因。3. 一键安装脚本install.sh 自动化了最繁琐的注册流程根据你指定的浏览器chrome / chromium / brave / edge / firefox推导配置目录用sed把清单中的占位路径替换为本机ff2mpv.py的真实路径再复制到正确位置。Windows 用户则使用 install.ps1 完成注册表写入。新手提醒更新扩展后一定要同步更新 Native Host否则版本不匹配会导致消息发送失败——README 中特别强调了这一点。六、选项页与配置档案Storage API 实战档案功能展示了 MV3 扩展中UI 层 ↔ 后台层 ↔ 存储层的标准协作模式UI 层options.html 是一个极简单页面顶部有一条醒目的安全警告——arbitrary MPV flags should be considered arbitrary code提醒用户档案里的参数等同于执行任意命令逻辑层options.js 用crypto.randomUUID()为新档案生成 ID通过chrome.storage.sync读写profiles键并检查chrome.runtime.lastError处理消息错误同步层选项页每保存一个档案就发一条createProfile/updateProfile/deleteProfile消息给 Service Worker由后台同步增删右键菜单项。选择storage.sync而非本地存储意味着档案会跟随用户账号跨设备同步——这是配置类数据的最佳实践。七、新手动手从零复现这个架构如果你想把这套架构迁移到自己的项目只需 4 步准备仓库代码如需本地调试源码git clone https://gitcode.com/gh_mirrors/ff/ff2mpv照抄清单骨架参考 manifest.json保留manifest_version: 3、双background声明和最小权限集实现事件中枢以 ff2mpv.js 为模板把action.onClicked里的 URL 转发逻辑换成你需要的动作打通本地程序仿照 ff2mpv.py 实现 stdin/stdout 帧协议再用 install.sh 或 install.ps1 的模式注册宿主清单。完成后你会发现一个功能完整的 MV3 扩展核心代码量其实非常可控。八、打包与发布dist.files 清单驱动ff2mpv 的发布流程同样值得借鉴dist.files 维护一份扩展包含哪些文件的清单manifest.json、ff2mpv.js、LICENSE、icons/、options/package-firefox.sh 按清单打包dist.zip供 Firefox Add-ons 商店提交package-chromium.sh 按清单拷贝到dist/目录再调用chrome --pack-extension生成.crx并复用dist.pem私钥保证扩展 ID 稳定。清单驱动打包的好处Native Host 脚本、安装脚本等扩展之外的文件不会混进发布包边界清晰。九、总结从 ff2mpv 提炼的 MV3 架构清单回顾 ff2mpv 的架构设计可以提炼出一份新手可直接套用的 MV3 扩展设计要点✅最小权限用activeTab、storage等低权限 API 组合解决 90% 的需求✅事件驱动Service Worker 中只注册监听器不写常驻逻辑✅兼容声明scriptsservice_worker双写一份后台代码通吃两大引擎✅stdio 帧协议Native Messaging 是扩展与本地世界通信的唯一正规通道长度头 JSON 必须严格遵守✅白名单安全allowed_extensions/allowed_origins一个都不能少✅lastError 检查回调式 API 的错误都在这里MV3 新手的第一坑✅清单驱动打包dist.files让发布内容与项目文件解耦。ff2mpv 用最少的代码演示了一个能真正跑在生产环境的 Manifest V3 扩展应该长什么样。把它克隆到本地、逐文件读一遍你会比看十篇教程都更理解 MV3 扩展架构的设计精髓。【免费下载链接】ff2mpvA Firefox/Chrome add-on for playing URLs in mpv.项目地址: https://gitcode.com/gh_mirrors/ff/ff2mpv创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 如何用Manifest V3开发一个实用浏览器扩展：ff2mpv架构设计完整剖析
如何用Manifest V3开发一个实用浏览器扩展ff2mpv架构设计完整剖析【免费下载链接】ff2mpvA Firefox/Chrome add-on for playing URLs in mpv.项目地址: https://gitcode.com/gh_mirrors/ff/ff2mpvff2mpv 是一个基于Manifest V3开发的轻量级浏览器扩展支持 Firefox、Chrome 及所有基于 Chromium 的浏览器。它的功能非常直接点击工具栏图标就能把当前网页链接交给本地的mpv 播放器打开播放右键页面上的链接、图片或视频同样可以一键Play in MPV。正因功能极简ff2mpv 成为学习 Manifest V3 扩展架构的绝佳样本——它的整个核心逻辑不到 300 行代码却完整覆盖了 MV3 开发中的四大核心机制manifest.json配置、Service Worker 后台脚本、Native Messaging 本地通信、Storage API 配置持久化。本文将以 ff2mpv 为例带你完整剖析一个实用浏览器扩展的架构设计。一、先认识 ff2mpv功能与使用方式ff2mpv 提供两种使用方式操作效果点击工具栏小图标将当前标签页 URL发送给 mpv 播放右键链接 / 图片 / 视频 / 选中文本在上下文菜单中选择Play in MPV播放它还有一个进阶功能——配置档案Profile你可以在选项页为不同场景保存一组 mpv 启动参数例如硬件加速、音频输出设备然后在右键菜单中按档案播放。扩展本身只负责传 URL真正的播放由你电脑上的 mpv 完成这也是后文要讲的 Native Messaging 架构的价值所在。二、项目文件结构MV3 扩展的最小骨架ff2mpv 的文件组成非常精简这也是 MV3 扩展推荐的组织方式文件/目录作用manifest.json扩展的身份证声明版本、权限、入口ff2mpv.js后台 Service Worker处理所有事件与消息ff2mpv.py原生消息宿主Native Host负责拉起 mpvoptions/options.html选项页界面管理播放参数档案options/options.js选项页逻辑读写 storage 并同步菜单ff2mpv.json / ff2mpv-chromium.json / ff2mpv-windows.json各浏览器的原生宿主注册清单install.sh / install.ps1Linux/macOS 与 Windows 的宿主安装脚本package-firefox.sh / package-chromium.sh打包发布脚本dist.files打包清单定义扩展包含哪些文件架构一图流文字版工具栏图标 / 右键菜单 │ ▼ ff2mpv.jsService Worker── 收集 URL 与参数 │ sendNativeMessage ▼ ff2mpv.pyNative Hoststdio 协议 │ Popen ▼ mpv 播放选项页则通过chrome.runtime.sendMessage与 Service Worker 通信把档案数据写入chrome.storage.sync。三、manifest.json 深度解析MV3 的 5 个关键配置manifest.json 是整个扩展的起点。ff2mpv 的清单里有 5 个值得新手重点学习的配置1. 双浏览器兼容的 background 声明background: { scripts: [ff2mpv.js], service_worker: ff2mpv.js }这是 MV3 开发的经典技巧service_worker是 Chrome 的 MV3 标准写法而旧版 Firefox 仍通过scripts加载。同时写两个键一份后台代码即可同时服务两大引擎。2. 用 action 替代 V2 的 browser_actionMV3 中工具栏图标由action字段声明ff2mpv 还通过commands中的_execute_action为图标操作提供了快捷键绑定。3. 权限最小化原则ff2mpv 申请了 5 个权限每个都有明确用途权限用途nativeMessaging与本地 Native Host 通信contextMenus创建右键菜单activeTab仅在用户点击时才获取当前标签页 URL比tabs更克制storage保存播放参数档案scripting播放前注入脚本暂停页面内的 HTML5 视频新手建议权限是扩展商店审核的重灾区能申请activeTab就不要申请tabs。4. options_ui在侧边栏打开选项页options_ui: { page: options/options.html, open_in_tab: false }open_in_tab: false让选项页以弹出面板形式打开交互体验更轻快。5. 浏览器身份声明browser_specific_settings.gecko.id为 Firefox 侧注册了ff2mpvyossarian.net这个唯一 ID——这是后续 Native Host 做来源白名单校验的前提。四、Service Worker 后台脚本事件驱动的消息中枢ff2mpv.js 是扩展的大脑。MV3 的 Service Worker 没有常驻 DOM、生命周期短暂所以它的设计哲学是一切皆事件。ff2mpv 注册了 5 类监听器构成完整的事件中枢️chrome.action.onClicked点击图标时直接取tab.url发给 Native Hostchrome.contextMenus.onClicked右键菜单点击时按优先级从info.linkUrl→srcUrl→selectionText→frameUrl中提取目标 URLchrome.runtime.onInstalled安装/更新后按已有档案重建右键菜单单条目或Profiles子菜单chrome.runtime.onMessage接收选项页的创建/更新/删除档案消息动态增删右键菜单项chrome.runtime.onMessageExternal接收外部应用如桌面工具发来的openVideo请求。其中有个 MV3 细节值得注意contextMenus.create仍是回调风格 APIff2mpv 用一个十几行的 Promise 包装器统一了 API 风格并检查chrome.runtime.lastError——在 MV3 中忽略 lastError 是新手最常见的坑。另外一个小而优雅的设计发起播放前它先用chrome.scripting.executeScript注入一段脚本暂停页面内所有video避免网页视频和 mpv 同时出声。五、Native Messaging打通浏览器与本地 mpv 的桥梁这是 ff2mpv 架构中最精彩的部分也是多数教程不会讲的进阶内容。1. 原理stdio 协议浏览器无法直接启动本地程序MV3 提供了 Native Messaging 机制扩展把消息发给一个原生宿主Native Host宿主从 stdin 读取、向 stdout 回复。ff2mpv.py 用不到 70 行 Python 实现了这个协议核心是4 字节消息长度 JSON 消息体的帧格式# 读取4 字节长度头 JSON length struct.unpack(I, sys.stdin.buffer.read(4))[0] message sys.stdin.buffer.read(length).decode(utf-8)收到{url: ..., options: [...]}后它组装命令行mpv --no-terminal options -- url并用subprocess.Popen启动最后回一句ok——必须回复否则浏览器控制台会报 An unexpected error occurred。代码里还藏着两个跨平台工程经验Windows 上需要CREATE_BREAKAWAY_FROM_JOB防止进程被任务管理器连带杀掉macOS 上图形应用的 PATH 继承自launchd看不到 Homebrew 安装的 mpv因此手动补了/opt/homebrew/bin到 PATH。这些坑在 README 和源码注释中都有记录是新手学习跨平台扩展开发的最佳实践素材。2. 宿主注册清单白名单安全机制Native Host 不是随便谁都能调用的必须注册 JSON 清单到浏览器指定目录且通过白名单校验来源Firefox 系ff2mpv.json用allowed_extensions校验扩展 IDChromium 系ff2mpv-chromium.json用allowed_origins校验扩展的 origin 地址Windowsff2mpv-windows.json宿主程序指向批处理脚本 ff2mpv.bat内部调用python ff2mpv.py。三套清单对应不同的注册位置浏览器配置目录下的NativeMessagingHosts/native-messaging-hostsWindows 则在注册表这正是项目里存在三个 JSON 文件的原因。3. 一键安装脚本install.sh 自动化了最繁琐的注册流程根据你指定的浏览器chrome / chromium / brave / edge / firefox推导配置目录用sed把清单中的占位路径替换为本机ff2mpv.py的真实路径再复制到正确位置。Windows 用户则使用 install.ps1 完成注册表写入。新手提醒更新扩展后一定要同步更新 Native Host否则版本不匹配会导致消息发送失败——README 中特别强调了这一点。六、选项页与配置档案Storage API 实战档案功能展示了 MV3 扩展中UI 层 ↔ 后台层 ↔ 存储层的标准协作模式UI 层options.html 是一个极简单页面顶部有一条醒目的安全警告——arbitrary MPV flags should be considered arbitrary code提醒用户档案里的参数等同于执行任意命令逻辑层options.js 用crypto.randomUUID()为新档案生成 ID通过chrome.storage.sync读写profiles键并检查chrome.runtime.lastError处理消息错误同步层选项页每保存一个档案就发一条createProfile/updateProfile/deleteProfile消息给 Service Worker由后台同步增删右键菜单项。选择storage.sync而非本地存储意味着档案会跟随用户账号跨设备同步——这是配置类数据的最佳实践。七、新手动手从零复现这个架构如果你想把这套架构迁移到自己的项目只需 4 步准备仓库代码如需本地调试源码git clone https://gitcode.com/gh_mirrors/ff/ff2mpv照抄清单骨架参考 manifest.json保留manifest_version: 3、双background声明和最小权限集实现事件中枢以 ff2mpv.js 为模板把action.onClicked里的 URL 转发逻辑换成你需要的动作打通本地程序仿照 ff2mpv.py 实现 stdin/stdout 帧协议再用 install.sh 或 install.ps1 的模式注册宿主清单。完成后你会发现一个功能完整的 MV3 扩展核心代码量其实非常可控。八、打包与发布dist.files 清单驱动ff2mpv 的发布流程同样值得借鉴dist.files 维护一份扩展包含哪些文件的清单manifest.json、ff2mpv.js、LICENSE、icons/、options/package-firefox.sh 按清单打包dist.zip供 Firefox Add-ons 商店提交package-chromium.sh 按清单拷贝到dist/目录再调用chrome --pack-extension生成.crx并复用dist.pem私钥保证扩展 ID 稳定。清单驱动打包的好处Native Host 脚本、安装脚本等扩展之外的文件不会混进发布包边界清晰。九、总结从 ff2mpv 提炼的 MV3 架构清单回顾 ff2mpv 的架构设计可以提炼出一份新手可直接套用的 MV3 扩展设计要点✅最小权限用activeTab、storage等低权限 API 组合解决 90% 的需求✅事件驱动Service Worker 中只注册监听器不写常驻逻辑✅兼容声明scriptsservice_worker双写一份后台代码通吃两大引擎✅stdio 帧协议Native Messaging 是扩展与本地世界通信的唯一正规通道长度头 JSON 必须严格遵守✅白名单安全allowed_extensions/allowed_origins一个都不能少✅lastError 检查回调式 API 的错误都在这里MV3 新手的第一坑✅清单驱动打包dist.files让发布内容与项目文件解耦。ff2mpv 用最少的代码演示了一个能真正跑在生产环境的 Manifest V3 扩展应该长什么样。把它克隆到本地、逐文件读一遍你会比看十篇教程都更理解 MV3 扩展架构的设计精髓。【免费下载链接】ff2mpvA Firefox/Chrome add-on for playing URLs in mpv.项目地址: https://gitcode.com/gh_mirrors/ff/ff2mpv创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考