业务痛点与技术封锁#

YouTube 具有非常严苛的防爬虫机制。其官方的字幕数据接口（/api/timedtext）强依赖于前端播放器动态生成的加密签名（Signature）。如果我们像普通的插件那样，在 Content Script 中手动发起 fetch 请求去拉取字幕数据，必然会遭遇 403 Forbidden 的无情拦截。

同时，Chrome 插件的 Content Script 默认运行在安全隔离的 ISOLATED World 中，根本无法触碰或修改宿主页面的 window.fetch 或 XMLHttpRequest，这就断绝了“普通抓包”的可能。

架构攻坚：Main World 注入与底层 Hook#

为了拿到带有官方合法签名的字幕数据，我利用了 Plasmo 提供的 world: "MAIN" 能力，在页面加载的第一时间（run_at: "document_start"），将一段名为 youtube-main-world.ts 的探针脚本注入 YouTube 真实的主执行环境。

在这个没有沙箱限制的世界里，我直接重写了原生的 window.fetch，并在不破坏官方请求的前提下，将返回的 JSON 字幕流通过 clone() 提取出来，最后使用一个安全的 Token 握手机制，通过 postMessage 传递回插件的隔离上下文中。

flowchart TD
    subgraph MAIN ["YouTube 真实页面环境 (MAIN World)"]
        YT["YouTube 原生播放器"] -->|"发起带签名的请求"| FetchHook["被拦截的 window.fetch"]
        FetchHook -->|"发送真实网络请求"| Server[("YouTube Backend")]
        Server -->|"返回 JSON 字幕数据"| FetchHook
        FetchHook -->|"Response.clone() 提取数据"| Dispatcher["postMessage (附带 Token)"]
    end

    subgraph ISOLATED ["插件沙箱环境 (ISOLATED World)"]
        Dispatcher -->|"监听 window message"| CS["Content Script 中枢"]
        CS -->|"解析字幕流存入 Zustand"| Store[("Zustand Store")]
    end

核心注入代码 (src/contents/main-world/hook-fetch.ts)：

1
export function setupFetchHook(getHandshakeToken: () => string) {
2
  const originalFetch = window.fetch
3

4
  // 强行重写宿主环境的 fetch
5
  window.fetch = async function (...args) {
6
    const url = args[0] instanceof Request ? args[0].url : args[0]?.toString() || ""
7
    const response = await originalFetch.apply(this, args)
8

9
    try {
10
      // 如果拦截到的是目标 timedtext (字幕) 接口
11
      if (isTimedTextUrl(url)) {
12
        // 规避掉贴片广告的无关字幕
13
        if (!isAdVideo(url)) {
14
          const clone = response.clone()
15
          clone.json().then((data) =>
16
            // 通过握手 Token 将原汁原味的官方数据派发回插件沙箱
17
            dispatchCaptionEvent(url, data, getHandshakeToken())
18
          ).catch(() => {})
19
        }
20
      }
21
    } catch {}
22

23
    // 将毫无篡改的 Response 返回给 YouTube 官方逻辑，保证播放器不出错
24
    return response
25
  }
26
}

此外，为了保证 YouTube 必然会发起字幕请求，我还编写了 ensureCCEnabled 轮询方法，模拟真实的物理点击，去自动点亮原生播放器上的 CC 按钮。

业务痛点#

YouTube 原生播放器的 DOM 非常复杂且动态变化。如果我们贸然删除其原生的字幕节点，会导致官方内部的代码逻辑（如位置计算、重绘机制）报出 TypeError 并导致播放器崩溃。 同时，我们自己用 Tailwind 编写的 React 双语字幕 UI，绝不能被宿主页面（YouTube）原有的全局 CSS 污染，也不能去污染宿主。

架构攻坚：Shadow DOM 与动态 Class 屏蔽#

1. 绝对隔离的 Shadow DOM： 我利用 Plasmo 的 getInlineAnchor 特性，将整个 React 渲染树挂载在 #movie_player 内部的影子节点中（Shadow Root）。这样外部的 CSS 穿透不进插件，插件的 Tailwind 工具类也不会泄露到外部。

2. 原生降级策略（“隐形”而非“抹杀”）： 我没有去删除原生的 CC 节点，而是在全局动态注入了一段高优先级的脱离流样式 <style>。当用户开启了 TubeWidget 双语字幕时，通过赋予宿主播放器 .tube-widget-active 标志，彻底将原生字幕在视觉和交互上隐形，但保留其在 DOM 树中的物理存在。

1
// 动态隐藏 YouTube 原生字幕渲染（配合 UI 层控制）
2
function injectDynamicSubtitleHider() {
3
  if (document.getElementById("ytranslater-dynamic-cc-hider")) return
4

5
  const style = document.createElement("style")
6
  style.id = "ytranslater-dynamic-cc-hider"
7
  // 当播放器具有 tube-widget-active 标志时，彻底隐藏所有原生字幕容器及指针事件
8
  style.textContent = `
9
    .tube-widget-active .ytp-caption-window-container { opacity: 0 !important; pointer-events: none !important; }
10
    .tube-widget-active .caption-window { opacity: 0 !important; pointer-events: none !important; }
11
  `
12
  document.head.appendChild(style)
13
}

3.1 业务踩坑：突破 CSP 限制与 Main World 劫持的竞态条件#

在实现 Main World 注入时，新手最容易踩的坑是竞态条件 (Race Condition)。 YouTube 并不是传统的刷新式网页，它重度使用了 SPF (Structured Page Fragments) 和自研的 Polymer 框架进行基于 history.pushState 的无刷新前端路由跳转。

如果你只是在 document_start 时注入了一次 fetch 拦截器，当用户从首页点击进入一个新视频时，YouTube 的前端路由接管了页面，此时你的拦截器很容易在某些边界情况下失效，或者你的 UI 挂载点 (Mount Point) 直接被 YouTube 动态更新的 DOM 树连根拔起销毁掉。

工业级解法：双重守护机制

1. 底层探针的持久化：我们在注入 fetch 拦截器时，不仅要重写原生的 window.fetch，还要同时拦截浏览器的 history.pushState 和 history.replaceState。一旦检测到 URL 发生带有 /watch?v= 的切换，拦截器会主动向插件的 Isolated World 发送一个 PAGE_NAVIGATED 心跳，唤醒处于休眠状态的 Content Script。
2. DOM 挂载点的 MutationObserver 霸体：在 UI 层，为了防止我们的双语字幕容器被 YouTube 删掉，我们不能只执行一次 document.body.appendChild。必须利用 MutationObserver 死死盯住 YouTube 播放器的内部节点（如 .html5-video-player）。一旦发现我们的字幕容器 #tube-widget-root 消失了，立刻在下一帧（Next Tick）把它原地复活重建。

3.2 业务踩坑：Shadow DOM 的事件穿透与 React 18 挂载冲突#

为了保证我们的 Tailwind CSS 绝对不污染 YouTube，也绝对不被 YouTube 那套写得非常宽泛的全局 CSS 污染，Shadow DOM 是唯一解。

但在将 React 18 应用渲染到 Shadow DOM 内部时，有一个极其著名的历史遗留大坑：React 的合成事件系统 (Synthetic Events) 默认是绑定在 document 根节点上的。 由于 Shadow DOM 的边界隔离特性（Event Retargeting），当你点击 Shadow DOM 里的一个按钮时，事件冒泡到 document 时，事件的 target 会变成整个 Shadow Host 本身，而不是那个按钮。这会导致 React 内部的事件系统完全错乱，你的 onClick 根本不会触发！

工业级解法：利用 React 18 的 createRoot 穿透

幸运的是，React 18 修改了事件委托机制。事件不再绑定到 document，而是绑定到了你调用 createRoot 的那个根节点容器上。 我们在 Plasmo 中，必须极其小心地手动接管 Shadow Root 的挂载逻辑：

1
// 必须挂载在 Shadow DOM 的内部容器上，而不是 Shadow Host 上！
2
const shadowHost = document.createElement('div');
3
shadowHost.id = 'tube-widget-host';
4
const shadowRoot = shadowHost.attachShadow({ mode: 'open' });
5

6
// 必须在 Shadow Root 里再套一层 div 作为 React 的 Root
7
const reactRootContainer = document.createElement('div');
8
reactRootContainer.id = 'tube-widget-react-root';
9
shadowRoot.appendChild(reactRootContainer);
10

11
// Tailwind 样式流必须动态打入这个 Shadow Root 内部
12
const styleSheet = document.createElement('style');
13
styleSheet.textContent = tailwindCssString;
14
shadowRoot.appendChild(styleSheet);
15

16
// 最后，将 React 18 挂载在这个被完全隔离的内部节点上
17
// 此时 React 的合成事件监听器会绑定在 reactRootContainer 上，完美避开 Shadow DOM 穿透问题
18
const root = createRoot(reactRootContainer);
19
root.render(<App />);

通过这套严密的嵌套解法，我们不仅实现了像素级的样式物理隔离，还保全了 React 复杂的交互能力。

业务痛点#

调用外部的大模型或 DeepL API 翻译一句话存在不可忽视的网络延迟（通常在几百毫秒到一两秒不等）。如果在字幕出现的那一瞬间才去触发 translate 请求，双语字幕必然会严重脱节，用户体验极差。

架构攻坚：Look-ahead Prefetch Pipeline (滑动窗口预加载)#

1. 毫秒级时间帧同步与跳变阻断 (Seek Handling)： 除了抛弃粗糙的 setInterval 改用 requestAnimationFrame 同步 <video>.currentTime，这里还有一个非常复杂的边界场景（Edge Case）：如果用户突然在进度条上拖拽跳跃了 30 分钟呢？ 我的底层状态机能够精准侦测到这类非线性的时间跳变 (Time Seek)。当检测到 currentTime 与上一帧的差值大于设定的阈值时，系统会立刻中断旧的预加载队列，废弃掉正在路上的无关网络请求，并在跳跃后的新基准线上重新建立 baseIndex 的 5 句缓存流水线。

2. 超前滑动窗口翻译： 在 UI 渲染的骨干 Overlay 组件中，我设计了一个超前滑动窗口流水线。当前视频线性播放到某一句字幕时，程序会自动向前探知之后的 5 句字幕 (PREFETCH_COUNT = 5)，并在后台静默派发翻译任务。

flowchart LR
    CurrentTime["当前播放时间轴 (currentTime)"] --> SubtitleN["当前渲染: 句子 N"]
    SubtitleN --> Window{"触发预加载机制"}
    Window -->|"预发网络请求"| PrefetchN1["预发网络请求: 句子 N+1"]
    Window -->|"预发网络请求"| PrefetchN2["预发网络请求: 句子 N+2"]
    Window -->|"预发网络请求"| PrefetchN3["预发网络请求: 句子 N+3..."]
    
    PrefetchN1 --> Cache[("IndexedDB 本地缓存")]
    PrefetchN2 --> Cache
    
    TimelineMove["时间轴推进到 N+1"] --> ReadCache["直接从本地缓存读取译文，实现 0 毫秒渲染延迟"]

核心预加载引擎代码 (src/contents/overlay/index.tsx)：

1
useEffect(() => {
2
  // ...省略环境与边界判断
3

4
  // 找到当前时间轴对应的基准字幕下标
5
  let baseIndex = currentSegment
6
    ? segments.findIndex((s) => s.id === currentSegment.id)
7
    : segments.findIndex((s) => s.tStartMs >= currentTimeMs);
8

9
  if (baseIndex === -1) return;
10

11
  const PREFETCH_COUNT = 5; // 永远提前预加载后续的 5 句字幕
12

13
  for (let i = 0; i <= PREFETCH_COUNT; i++) {
14
    const nextIndex = baseIndex + i;
15
    // 如果该片段尚未被预加载过，则推入预加载队列
16
    if (nextIndex < segments.length && nextIndex > maxPrefetchedIndexRef.current) {
17
      const nextSegment = segments[nextIndex];
18
      // 底层自动查库/发起网络请求，并缓存到 IndexedDB
19
      prefetchTranslation(nextSegment.text, settings.targetLang);
20
      maxPrefetchedIndexRef.current = nextIndex;
21
    }
22
  }
23
}, [currentSegment?.id, segments.length, settings?.targetLang, currentTimeMs]);

配合传递到打字机 UI 组件 (Subtitle) 上的 durationMs（该段字幕的物理寿命），实现了原生般流畅、绝不卡顿的双语同轨显示。