本文详解如何在 Manifest V3 下确保扩展脚本在目标网站 js 执行前完成初始化，通过 world: “MAIN” 直接注入全局变量，彻底解决 document_start 仍晚于页面脚本的问题。
本文详解如何在 manifest v3 下确保扩展脚本在目标网站 js 执行前完成初始化，通过 `world: “main”` 直接注入全局变量，彻底解决 `document_start` 仍晚于页面脚本的问题。
在 chrome 扩展开发中，若需向网页环境（即 window 全局作用域）提前注入变量或补丁（如 window.someVar = true），传统做法是通过 content script 动态创建 <script> 标签加载外部 JS 文件。但该方式存在本质缺陷：即使 content script 设置为 "run_at": "document_start"，其注入的脚本仍运行在独立的隔离世界（Isolated World），且实际执行时机受 dom 解析与脚本调度影响，<strong>往往滞后于页面内联/外部脚本的执行——导致目标网站 JS 读取不到预期的全局变量。</script>
自 Chrome 111 起，Manifest V3 原生支持 “world”: “MAIN” 配置项，使 content script 直接运行在页面主 JavaScript 环境（MAIN world）中，从而实现真正意义上的“早于页面脚本执行”。这是目前最简洁、可靠、符合规范的解决方案。
✅ 正确实现方式
只需两步改造，无需额外文件或事件通信：
- 移除所有间接注入逻辑：删除 injected.js 文件及 web_accessible_resources 声明；
- 将初始化代码直接写入 content.js，并在 manifest 中声明 world: “MAIN”。
更新后的 manifest.json：
立即学习“Java免费学习笔记（深入）”；
{ "name": "script-injector", "manifest_version": 3, "version": "0.0.1", "content_scripts": [{ "matches": ["*://localhost:*/*", "*://127.0.0.1:*/*"], "js": ["content.js"], "run_at": "document_start", "world": "MAIN" }] }精简后的 content.js（无任何 DOM 操作）：
// 此代码直接运行在页面 window 上下文中 console.log("CE: Initialized in MAIN world"); window.someVar = true; window.API_OVERRIDE = { enabled: true };✅ 效果验证：此时 console.log 将出现在页面自身脚本日志之前；window.someVar 在页面任意 <script> 中均可立即访问。</script>
⚠️ 关键注意事项
-
*`chrome.API 不可用**：运行在MAINworld 的脚本无法调用chrome.runtime、chrome.storage等扩展 API（会报undefined` 错误）。如需读取配置或发送消息，应采用双 content script 架构：
- MAIN world script（world: “MAIN”）：仅负责设置全局变量、劫持原生方法等 DOM 层操作；
- Isolated world script（默认 world: “ISOLATED”）：负责调用 chrome.* API，并通过 window.postMessage() + window.addEventListener(‘message’, …) 与 MAIN world 安全通信。
-
run_at: “document_start” 仍是必要前提：它确保脚本在
解析初期即注入，避免被后续 <script defer> 或模块脚本抢占时机。</script>
-
不兼容旧版 Chrome：”world”: “MAIN” 仅支持 Chrome 111+。如需兼容更低版本，必须回退至动态 <script> 注入 + document.write()（不推荐）或 MutationObserver 监听 <head>（复杂且不可靠）。</script>
✅ 总结
| 方案 | 执行时机 | 全局变量可访问性 | 可用 chrome.* API | 维护成本 |
|---|---|---|---|---|
| 动态 <script> 注入</script> | ❌ 滞后（常见） | ✅（但时机不可控） | ✅ | 中（需额外文件/资源声明） |
| world: “MAIN” + document_start | ✅ 真正最早 | ✅（同步、确定） | ❌ | 低（零配置、单文件） |
推荐实践：优先使用 world: “MAIN”；若需扩展能力，搭配轻量级 postMessage 通信即可兼顾安全性与功能性。此方案不仅是技术升级，更是对 Chrome 扩展现代架构的最佳实践遵循。