iTerm2 WebExtensions 框架 content_scripts 字段完全指南从 manifest 声明到注入执行【免费下载链接】iTerm2iTerm2 is a terminal emulator for Mac OS X that does amazing things.项目地址: https://gitcode.com/gh_mirrors/it/iTerm2content_scripts是 WebExtensions Manifest 中用于声明内容脚本的核心字段它告诉浏览器/扩展宿主在哪些 URL 匹配的网页中加载并执行自定义 JavaScript 与 CSS。本文以 iTerm2 仓库内置的 WebExtensionsFramework位于 WebExtensionsFramework为背景完整讲解content_scripts字段的每个属性、取值含义、JSON 示例并结合 ExtensionManifest.swift 的 Swift 模型与仓库内测试用例从 manifest 解析、校验到脚本加载的完整链路帮助你写出可复制、可运行的扩展配置。一、字段概览类型、必填性与作用在 Manifest V3 规范中content_scripts属于可选顶层字段manifest_version、name、version为必填项完整字段清单见 manifest-v3-spec.md。TypeArray of Objects对象数组RequiredNo可以不声明该字段作用指示扩展宿主browser/宿主应用将内容脚本加载到URL 与 match pattern 匹配的网页中从而在页面上下文中注入样式与行为代码。content_scripts: [ { matches: [all_urls], js: [content.js], css: [styles.css], run_at: document_idle } ]数组中的每个对象代表一个独立的内容脚本注册registration可以针对不同的 URL 模式、注入时机分别配置。二、对象属性详解每个内容脚本对象由 1 个必填属性和 9 个可选属性组成下面逐一说明。2.1 必填属性matches类型Array of stringsmatch patternsURL 匹配模式数组约束至少提供一个模式否则该注册无效作用声明内容脚本要注入到的 URL 范围matches是内容脚本的准入名单最常见的取值是all_urls匹配所有 http/https 页面也可以精确到某个站点例如matches: [ https://example.com/*, https://*.github.com/*, *://localhost/* ]模式语法遵循标准的 match patterns 规则*可匹配任意子串all_urls是匹配http、https、file等协议的全量通配写法。2.2 可选属性js注入的 JavaScript 文件类型Array of strings文件路径数组作用列出要注入到匹配页面中的 JS 文件。路径相对于扩展包的根目录。css注入的 CSS 文件类型Array of strings文件路径数组作用列出要注入的样式文件用于在页面加载早期统一打补丁式地修改外观。all_frames类型Boolean默认值false作用true时注入所有 frame包括 iframe 等子框架false时仅注入顶层 frame。run_at注入时机类型String默认值document_idle可选值document_start文档开始加载、DOM 尚未构建时注入适合尽早挂载事件监听document_endDOM 解析完成、图片等子资源仍在加载时注入document_idle文档加载完成后的空闲时机注入默认值性能影响最小。world脚本执行上下文类型String默认值ISOLATED可选值ISOLATED在隔离的 JavaScript 世界中执行页面自身脚本无法直接访问扩展注入的变量安全性更高默认MAIN在主世界页面自身环境中执行可访问/修改页面的全局对象。exclude_matches排除模式类型Array of stringsmatch patterns作用即使 URL 命中matches若同时命中exclude_matches中的模式则不注入。用于在大范围匹配时精确排除少数页面。include_globs额外包含通配类型Array of stringsglob patterns作用在matches基础之上用更灵活的 glob 通配额外圈入符合条件的 URL。exclude_globs排除通配类型Array of stringsglob patterns作用用 glob 通配进一步排除不需要注入的 URL。match_about_blank类型Boolean作用true时允许注入到about:blank页面前提是导航源页面本身匹配注入条件。match_origin_as_fallback类型Boolean作用true时允许注入到**不透明来源opaque origin**的页面——例如通过data:、blob:等协议创建的文档其来源无法用常规 match pattern 描述需要该开关兜底。三、完整 JSON 示例与关键行为原文档给出的最小可用示例也是仓库测试扩展实际采用的配置content_scripts: [{ matches: [all_urls], js: [content.js], run_at: document_end }]在此基础上把上述可选属性全部用上可得到一份覆盖面完整的配置content_scripts: [{ matches: [https://*.example.com/*, https://example.org/*], exclude_matches: [https://example.org/help/*], js: [lib/utils.js, content.js], css: [content.css], run_at: document_idle, all_frames: false, world: ISOLATED, include_globs: [*example*], exclude_globs: [*test*], match_about_blank: false, match_origin_as_fallback: false }]原文档明确的三个注入行为要点务必牢记脚本按数组顺序注入js数组中靠前的文件先注入因此依赖关系要按书写顺序排列CSS 先于 JavaScript 应用样式注入发生在 JS 之前JS 执行时页面已带有注入样式每个对象是独立注册同一content_scripts数组中的不同对象互不影响可分别面向不同页面/时机配置。四、源码级解析Swift 模型与 JSON 映射iTerm2 的 WebExtensionsFramework 用 SwiftCodable结构体精确建模了该字段实现位于 ExtensionManifest.swiftpublic struct ContentScript: Codable { public let matches: [String] // 必填URL 匹配模式 public let js: [String]? // 可选注入的 JS 文件 public let css: [String]? // 可选注入的 CSS 文件 public let runAt: ContentScriptRunAt? // 可选注入时机 public let allFrames: Bool? // 可选是否注入所有 frame public let world: ContentScriptWorld? // 可选执行上下文 public let excludeMatches: [String]? // 可选排除的 URL 模式 public let includeGlobs: [String]? // 可选额外包含 glob public let excludeGlobs: [String]? // 可选排除 glob public let matchAboutBlank: Bool? // 可选about:blank 注入 public let matchOriginAsFallback: Bool? // 可选不透明来源注入 enum CodingKeys: String, CodingKey { case matches case js case css case runAt run_at case allFrames all_frames case world case excludeMatches exclude_matches case includeGlobs include_globs case excludeGlobs exclude_globs case matchAboutBlank match_about_blank case matchOriginAsFallback match_origin_as_fallback } }有两点值得注意枚举约束了取值run_at被建模为ContentScriptRunAt枚举documentStart/documentEnd/documentIdleworld被建模为ContentScriptWorld枚举isolated/main非法取值会在解码阶段直接失败从源头保证配置合法性见 ExtensionManifest.swift。snake_case ↔ camelCase 自动转换通过CodingKeys显式映射manifest 中的run_at、all_frames、exclude_matches、match_about_blank等 JSON 字段与 Swift 属性一一对应顶层ExtensionManifest则通过contentScripts content_scripts挂载该数组见 ExtensionManifest.swift。五、注入与加载链路从 manifest 到页面脚本content_scripts不只是一份声明框架会在扩展加载阶段真正读取并缓存脚本内容。相关逻辑位于 BrowserExtension.swiftloadContentScripts()遍历 manifest 中的每个ContentScript逐个调用loadContentScriptResource加载资源若 manifest 未声明该字段则安全返回空数组contentScriptResources []loadContentScriptResource(_:)按js数组顺序逐个读取文件内容组装为ContentScriptResource包含原始ContentScript配置与已加载的 JS 文本文件缺失会抛出ContentScriptLoadingError.fileNotFoundIO 失败抛出ioError见 BrowserExtension.swift。也就是说从配置结构看matches决定注入范围、js决定注入内容、run_at与world决定注入时机与上下文这一整套信息最终由注入脚本生成器BrowserExtensionContentScriptInjectionGeneratorProtocol见 BrowserExtensionActiveManager.swift转换为实际的页面注入操作。六、仓库内真实用例与测试验证仓库中的测试扩展是理解content_scripts的最佳活教材red-box/manifest.json在all_urls的每个页面顶部注入一个红色方框采用run_at: document_end是每页注入 UI的经典最小案例storage-ui-demo/manifest.json同时声明permissionsstorage、background.service_worker与content_scripts展示内容脚本与后台 Service Worker 协同的完整形态单元测试 RedBoxExtensionTests.swift 直接用与 manifest 完全一致的 JSON 做解码断言并校验ManifestValidator校验通过ExtensionManifestTests.swift 覆盖了三种典型场景完整解码、字段整体可选未声明时contentScripts为nil、最小必填仅matchesjs/css/run_at均为nil——这印证了原文档只有matches必填的规则。七、最佳实践与注意事项先写matches再考虑收窄大范围匹配如all_urls配合exclude_matches/exclude_globs收窄比逐条列举 URL 更易维护依赖顺序敏感多个 JS 文件存在依赖时被依赖文件必须排在js数组前面尽早注入用document_start需要拦截网络请求或最早挂载监听器时使用默认的document_idle对页面性能影响最小非必要不使用MAIN世界ISOLATED隔离了页面与扩展的变量空间可避免与页面脚本冲突也防止页面篡改扩展逻辑match_about_blank与match_origin_as_fallback按需开启它们应对的是about:blank与data:/blob:等特殊文档来源普通站点注入无需开启。八、延伸阅读相邻字段规范background.md、permissions.md、host_permissions.mdManifest V3 全字段清单manifest-v3-spec.md扩展包结构约定package-structure.md后台脚本实现规划Background_Scripts_Implementation_Plan.md可运行的测试扩展目录test-extensions。【免费下载链接】iTerm2iTerm2 is a terminal emulator for Mac OS X that does amazing things.项目地址: https://gitcode.com/gh_mirrors/it/iTerm2创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考