mv3网站视频无法播放？照着这份排查清单逐项修复
如果你正在把扩展从 Manifest V2 迁到 V3，最近最常见的一类回归就是 mv3网站视频无法播放：页面结构没变、接口也通，但 <video> 只剩一张 poster，点播放毫无反应。本文不绕弯，先给现象与根因，再给可以直接照抄的修复代码。
首屏问题速览：mv3 下视频无法播放的典型现象
2026 年这一轮迁移潮里，绝大多数「升级 MV3 之后视频就没了」的反馈都集中在下面几类表现上。先对号入座，能省掉一半排查时间。
- 黑屏但控件在：video 元素高度正常、时长也能读到，点击播放按钮后进度不动，画面始终为黑。
- 控制台报 CSP：出现
Refused to load the script ... because it violates the following Content Security Policy directive，这类直接指向 CSP 与远程代码问题。 - 请求被拒：网络面板里播放器分片或扩展内资源返回
net::ERR_BLOCKED_BY_RESPONSE，通常与web_accessible_resources有关。 - 取流跨域失败：manifest 里没写
host_permissions，后台 fetch 视频地址时被 CORS/权限拦下。
影响范围不小：凡是「扩展注入播放器」「content script 动态创建 video」「用 chrome.scripting 插入远程脚本」的站点，迁移后基本都要按本文的顺序过一遍。具体原理见根因剖析与深度原理。
根因剖析：CSP 与权限变更如何拦截视频
MV3 把「能跑什么代码」和「能访问哪些资源」这两件事同时收紧了，而视频播放恰好同时踩在这两条线上，所以表现才会这么集中。
CSP：extension_pages 默认只信自己
MV3 扩展页面的默认 CSP 是 script-src 'self'; object-src 'self'，并且不允许通过 unsafe-eval、unsafe-inline 放宽。V2 时代从 CDN 拉一个 hls.js 就能跑，现在这条路径直接被切断——播放器脚本没执行，video 自然永远是黑屏。
远程托管代码禁令
即使你换成 import() 或 new Function 拼装播放逻辑，也会被判定为远程托管代码。结论很直接：播放器必须随扩展一起打包。
权限模型拆分：permissions 与 host_permissions
MV3 把域名权限从 permissions 拆到了 host_permissions。视频 CDN、分片域名、接口域名如果没逐条声明，跨域取流就会被拦；同时 web_accessible_resources 也从数组升级为带 resources 与 matches 的对象数组，漏写就无法被页面读取。修复写法见修复代码与最小示例。
深度原理：MV3 的媒体加载链路为什么更容易断
理解链路，比记住报错有用得多。播放一个视频，实际要经过四道关口，MV3 把其中三道都改了规则。
一、脚本加载与执行上下文
浏览器扩展有独立的执行世界（isolated world），DOM 共享但 JS 作用域隔离。播放器若要接管页面里的 <video>，必须运行在页面的主世界（main world），否则拿到的元素实例与页面的原型链不一致，事件监听会静默失效。MV3 推荐用 chrome.scripting.executeScript 指定 world: 'MAIN'，而不能再依赖往 DOM 里塞 <script> 标签——后者受页面自身 CSP 约束，成功率取决于目标站点策略。
二、资源来源与 CORS/CORB
视频分片通常跨域。MV3 的 service worker 没有页面的 origin 继承关系，fetch 跨域媒体时既受扩展权限约束，也受目标服务器 Access-Control-Allow-Origin 约束。即使权限写对，服务端不回 CORS 头，仍然会失败。这也是为什么同一份扩展「有的站点正常、有的站点黑屏」。
三、CSP 与 sandbox 页面的边界
MV3 允许定义 sandbox 页面并在其中放宽 CSP，但 sandbox 页面本身没有扩展 API 权限，也不能执行远程代码。指望用 sandbox 绕过远程播放器限制是行不通的，正确做法是自托管、自打包，把不可控的远程依赖消灭在构建阶段。这也是官方在“改善扩展安全性”上最核心的设计意图。
四、Service Worker 的生命周期
MV3 的背景页是事件驱动的 service worker，空闲即被回收。若把播放器的初始化状态放在全局变量里，唤醒后状态丢失，就会出现「第一次能播、切走再回来就不播」。状态应写入 chrome.storage，并在注入前重建。
核心排查步骤：按顺序定位视频加载失败
下面五步按「先证据、后结论」排列，建议一步一记，别跳步。完整现象对照见首屏速览。
- 复现并抓取报错原文。在注入页面打开 DevTools，控制台筛选
CSP，网络面板筛选media，把被拦截请求的 URL 与控制台原文一起记录下来。 - 确认播放器是否来自远程。搜索代码里的 CDN 地址、
import()、new Function、eval。命中任意一项，先按远程代码问题处理。 - 逐条核对 manifest 权限。检查
permissions与host_permissions，把视频域名、分片域名、接口域名全部列出，缺一个都会失败。 - 检查 web_accessible_resources。页面侧需要读取扩展内文件时，必须有
resources加matches，否则请求直接被拒。 - 换成自托管播放器并验证。把播放器打包进扩展，用
world: 'MAIN'注入，刷新页面观察是否仍有 CSP 报错。
提示：如果只有部分站点失败，优先查第 3 步和第 4 步；如果全部失败，优先查第 2 步。回退方案见兼容与回退策略。
修复代码与最小示例：可复制的 manifest 与播放器片段
先补齐清单文件。注意 extension_pages 的 CSP 只允许极少数指令，写多余指令会导致安装即报错，保持最小即可。
{
"manifest_version": 3,
"name": "video-helper",
"version": "1.2.0",
"permissions": ["scripting", "storage"],
"host_permissions": [
"https://media.example.com/*",
"https://cdn.example.com/*"
],
"content_security_policy": {
"extension_pages": "script-src 'self'; object-src 'self'"
},
"web_accessible_resources": [{
"resources": ["player.js", "player.css"],
"matches": ["https://www.example.com/*"]
}],
"background": { "service_worker": "sw.js" }
}第二步，改用主世界注入，把播放器真正放进页面上下文：
// sw.js —— 迁移后推荐注入方式
chrome.action.onClicked.addListener(async (tab) => {
if (!tab.id) return;
await chrome.scripting.executeScript({
target: { tabId: tab.id },
world: 'MAIN', // 关键：进入页面主世界
files: ['player.js'] // 已打包，非远程
});
});第三步，播放前的取流要显式带上权限与错误回执：
// player.js —— 主世界内初始化播放器
const v = document.querySelector('video');
if (v && !v.dataset.mv3Ready) {
v.dataset.mv3Ready = '1';
v.addEventListener('error', () => {
console.warn('media error', v.error && v.error.code);
});
// 自托管 hls 实例挂载：hls.js 已随扩展打包
if (window.Hls && Hls.isSupported()) {
const hls = new Hls({ enableWorker: false });
hls.loadSource(v.dataset.src);
hls.attachMedia(v);
} else {
v.src = v.dataset.src; // Safari / 原生 HLS 兜底
}
}验证要点：刷新页面后控制台不应再出现 CSP 报错；网络面板中播放器文件应来自
chrome-extension:// 而非 CDN；video 的 readyState 应大于 0。若仍失败，回到排查清单逐项核对。兼容与回退策略：多环境下的降级播放
修复之后，还要考虑「万一某类站点注入失败」的兜底，否则用户看到的就是一片空白。
能力探测优先于特性假设
先判断 Hls.isSupported()，再判断 video.canPlayType()，最后才决定用 MSE 还是原生播放。不要默认所有环境都能跑 MSE。
三层降级
- 第一层：MSE + 自托管 hls.js，覆盖 Chrome/Edge 等主流桌面环境。
- 第二层：原生 HLS，交给 Safari 与部分移动端内核自行解析。
- 第三层：直接给出直链与提示文案，保证用户至少能手动打开，避免无反馈的黑屏。
原则：注入失败必须是「可感知的失败」，而不是静默黑屏。任何一路失败都应留下日志与可见提示。
常见问题 FAQ：黑屏、报错与部分站点正常
为什么升级 MV3 后视频直接黑屏，控制台还有 CSP 报错？
这是最典型的一类。原因是原来的播放器脚本从 CDN 远程加载，而 MV3 的扩展页面 CSP 默认只允许 script-src 'self'，远程脚本被拒绝执行，播放器从未初始化。处理顺序：先确认报错里被拒的 URL 是否就是播放器地址；再把该文件下载并随扩展打包；最后改用 chrome.scripting.executeScript 的 world: 'MAIN' 注入。若你还在用往 DOM 插 <script> 标签的老写法，注意它同时会受目标站点自身 CSP 约束，成功率不稳定，建议一并替换。
为什么同一份扩展，有的站点能播、有的站点视频无法播放？
差异通常来自三处：目标站点的 CSP 是否放行了主世界脚本；视频分片服务器是否返回 CORS 响应头；以及你的扩展是否声明了该站点的 host_permissions 与 web_accessible_resources。做法：把失败站点的域名单独加进 host_permissions，核对 matches 是否覆盖该站点路径；如果站点 CSP 很严格，优先使用扩展自身页面承载播放，而不是强行在页面主世界注入。最后用网络面板逐条比对成功与失败站点的请求差异。
网络面板出现 ERR_BLOCKED_BY_RESPONSE，是权限写错了吗？
多数情况是 web_accessible_resources 没配对。MV3 要求写成对象数组，包含 resources（要暴露的文件）与 matches（允许读取的页面来源），二者缺一不可。注意：暴露范围尽量收窄到必要文件与必要站点，不要用 <all_urls> 图省事，这会扩大攻击面并影响上架审核。改完记得重新加载扩展，并关闭旧标签页重开，避免缓存了旧的资源声明。
第一次能播，切走标签页再回来就播不了了，怎么解？
这是 service worker 被回收导致的。MV3 的背景页是事件驱动的，空闲即终止，任何存在内存里的播放器状态都会丢失。修复：把必要状态写入 chrome.storage.session 或 chrome.storage.local，在每次注入前重新读取并重建实例；同时给重复注入加幂等标记（例如前面示例里的 dataset.mv3Ready），避免多次注入造成监听器叠加。
排查完仍然失败，还有哪些检查点？
确认三个容易被忽略的点：一是扩展是否已重新加载、旧版本是否仍在运行；二是目标页面是否是跨域 iframe，若是，权限与资源声明都要覆盖到内层来源；三是媒体响应是否带 Content-Range，缺失会导致部分播放器在 seek 时失败。合规提示：修复扩展的视频播放能力时，请遵守目标站点的使用条款与当地法律法规，仅在你拥有权限的站点与内容上使用，理性使用、勿用于绕过版权保护。
结尾：按清单自查，拿完整修复模板
回到最开始的问题：mv3网站视频无法播放并不是一个玄学 bug，它几乎总能归结为 CSP、远程代码、权限声明、资源暴露四件事中的一件。建议你现在就按五步排查清单走一遍，把每一步的证据记下来，一般 30 分钟内能定位到具体那一环。
定位之后，直接套用修复代码与最小示例中的 manifest 与注入片段，再按兼容与回退策略补上三层降级，就能兼顾覆盖率与体验。需要把上面所有片段拼成一份可直接导入的示例工程，可参考页脚的模板入口继续查阅。
本文示例基于 2026 年 9 月的 Chrome 稳定版行为整理，浏览器策略可能随版本调整，落地前请以官方文档与实机验证为准。