iTerm2 WebExtensionsFramework 中的 manifest_version 字段:Manifest V3 兼容性基石与源码解析
iTerm2 WebExtensionsFramework 中的 manifest_version 字段:Manifest V3 兼容性基石与源码解析
iTerm2 的 WebExtensionsFramework 为桌面终端应用引入了类浏览器扩展体系,而 manifest_version 正是每份扩展清单(manifest.json)中唯一强制要求且取值唯一的字段,它决定了扩展的结构与可用 API 集合。本指南以 manifest_version 官方字段文档 为主线,结合该框架的 Swift 实现与真实测试扩展,说明该字段的类型约束、校验机制、在仓库中的真实形态,以及它在 Manifest V3 与 V2 迁移语境下的设计含义,帮助读者在 iTerm2 中编写、调试与校验符合规范的 WebExtension 清单。
字段速览:Type / Required / Valid Values / Example
在深入源码之前,先给出该字段的官方契约(源自 manifest_version.md):
| 属性 | 取值 | 说明 |
|---|---|---|
| Type | Number |
JSON 数字类型,不是字符串,因此 "manifest_version": "3"(带引号)是不合法的 |
| Required | Yes | 每个 WebExtensions manifest.json 中该字段必须存在,是唯一必填字段 |
| Valid Values | 3 |
Manifest V3(当前标准);非 3 的取值在框架校验阶段直接报错 |
| Example | "manifest_version": 3 |
标准的完整写法 |
官方 Notes 还明确了三点约束:
- 该字段在每个 WebExtensions manifest 中都是强制的;
- 它决定了扩展的结构(structure)与可用能力(capabilities),即浏览器/宿主以哪套规范来解释其余字段;
- Manifest V3 扩展中该值必须恰好等于
3。
为什么是唯一必填字段:manifest 的结构与能力开关
从 manifest-v3-spec.md 可以看清 manifest_version 在整个清单体系中的位置:它被列为 Required Fields 中的第一个,与其并列的还有 name、version、description、icons;其余如 background、content_scripts、permissions、host_permissions、optional_permissions 等均属于可选字段。也就是说,一个只包含 manifest_version 的 manifest.json 也能被框架解析——它是扩展的"最小可辨识身份"。
manifest_version 之所以被提升为结构开关,是因为 WebExtensions 规范本身是版本化演进的:
- Manifest V2(值
2):采用常驻后台页面(background pages),支持"persistent": true的长生命周期模型; - Manifest V3(值
3,当前标准):改用事件驱动的 service worker 后台模型,引入host_permissions独立于permissions、默认非持久化后台、强制更严格的内容安全策略(CSP)等。
因此在解析器看来,manifest_version 的值直接决定后续字段(尤其是 background)按哪套语义解释。仓库中 background.md 文档也印证了这一点:"scripts": [...] 数组与 "persistent": true 被明确标注为 "Legacy approach (Manifest V2 compatibility)" 与 "Deprecated in Manifest V3",而 "service_worker": "background.js" 则是 V3 的首选写法。所有这些分支判断,都依赖于 manifest_version 先被正确解析。
源码级的解析与校验:ExtensionManifest 与 ManifestValidator
文档中的契约在 iTerm2 仓库内被一对 Swift 文件落地实现:清单数据结构与字段映射、以及启动时的强制校验。
数据结构与 JSON 键映射
ExtensionManifest.swift 定义了 ExtensionManifest 结构体,其中:
/// Specifies the version of manifest.json used by this extension
/// Reference: Documentation/manifest-fields/manifest_version.md
public var manifestVersion: Int
enum CodingKeys: String, CodingKey {
case manifestVersion = "manifest_version"
// ...
}
两点值得注意的实现事实(对应 ExtensionManifest.swift 与 ExtensionManifest.swift):
- 代码注释直接反向引用了本文档(
Reference: Documentation/manifest-fields/manifest_version.md),说明该字段文档是框架开发的规格来源; manifestVersion的类型是 SwiftInt,且通过CodingKeys将 JSON 中的manifest_version键显式映射到该属性——这与文档中"Type: Number"的声明严格对应。若清单中写成字符串"3",Swift 的Codable解码将直接失败。
运行时强制校验
ManifestValidator.swift 是启动校验的守卫。validate(_:) 的第一步就是校验清单版本:
public enum ManifestValidationError: Error, Equatable {
case invalidManifestVersion(Int)
// ...
}
private func validateManifestVersion(_ version: Int) throws {
guard version == 3 else {
logger.error("Invalid manifest version: \(version), expected: 3")
throw ManifestValidationError.invalidManifestVersion(version)
}
}
对应 ManifestValidator.swift 与 ManifestValidator.swift。这段实现把文档中"Must be exactly 3"的约束落成了可执行规则:任何非 3 的取值(包括缺失字段导致解码失败、或显式写成 2/4 等)都会抛出不兼容错误并记录日志。校验过程会在 validate 上下文中先打印 Validating manifest version: \(manifest.manifestVersion) 的调试日志,再执行 guard 判断,方便定位问题。
从错误类型设计还可以看出框架的校验分层:invalidManifestVersion 与 invalidBackgroundScript、backgroundScriptConflict 平级,说明版本校验是 manifest 整体合法性检查中的独立关卡,与后台脚本配置校验(如 service_worker 与 scripts 不可同时出现、路径必须以 .js 结尾)互不干扰。
真实扩展清单中的 manifest_version:仓库内可验证示例
iTerm2 仓库同时携带多份真实的 manifest.json 示例,可作为最直接的实操参照。
以 test-extensions/storage-demo/manifest.json 为例,它演示了包含权限与后台脚本的完整 V3 清单:
{
"manifest_version": 3,
"name": "Storage Demo",
"version": "1.0",
"description": "Demonstrates chrome.storage API functionality between background and content scripts",
"permissions": [
"storage"
],
"background": {
"service_worker": "background.js"
},
"content_scripts": [{
"matches": ["<all_urls>"],
"js": ["content.js"],
"run_at": "document_end"
}]
}
另一个最小化示例 Tests/WebExtensionsFrameworkTests/Resources/red-box/manifest.json 则展示了"只有必填字段 + content scripts"的极简形态:
{
"manifest_version": 3,
"name": "Red Box",
"version": "1.0",
"description": "Adds a red box to the top of every page",
"content_scripts": [{
"matches": ["<all_urls>"],
"js": ["content.js"],
"run_at": "document_end"
}]
}
两份清单的共性可以归纳出编写规范:
- 键名必须是下划线风格的
manifest_version(框架通过CodingKeys精确匹配,驼峰写法无法解码); - 值必须是裸数字 3,不带引号;
- 首行即声明版本,随后依次是
name、version、description等必填元数据,最后才是各可选能力块。
仓库内 test-extensions/ 目录下还有 count-logger、custom-user-agent、message-demo、storage-ui-demo 等示例,均以 "manifest_version": 3 开头,可作为批量参照:在 WebExtensionsFramework/test-extensions 目录下即可查看全部清单文件。
字段之间的联动:manifest_version 如何影响 background 与权限解析
manifest_version 的"结构开关"作用,在后台脚本(background)的解析上体现得最明显。参考 background.md 的 Object Properties:
service_worker:String,指向作为扩展 service worker 的 JS 文件路径,是 Manifest V3 的首选方式,运行在事件驱动的 service worker 上下文中;scripts:String 数组,V2 兼容的旧式后台脚本,共享同一 window 全局上下文,按数组顺序加载;persistent:Boolean,V3 默认false(service worker 天然非持久化,该字段已被弃用),仅在旧式scripts写法下有意义;type:String,默认"classic",可设为"module"以启用 ES6 import/export。
框架对上述规则的落地校验(见 ManifestValidator.swift)同样印证了 V3 语义:service_worker 与 scripts 必须二选一(同时出现或都缺失都会报错)、路径必须以 .js 结尾、type 只能是 "classic" 或 "module"。这些约束共同构成了"V3 下扩展如何声明后台逻辑"的完整回答。
此外,manifest-v3-spec.md 列出了 permissions、host_permissions、optional_permissions、optional_host_permissions 等权限字段——其中 host_permissions 与 optional_host_permissions 正是 V3 才从 permissions 中拆出的概念,进一步说明版本值会改变整个清单的解释空间。
检查清单与常见错误
综合文档契约与框架实现,编写 manifest_version 时可对照以下检查点:
- [ ] 键名是否为下划线写法
manifest_version(而非manifestVersion); - [ ] 值是否为裸数字
3(字符串"3"会解码失败,浮点3.0在严格 JSON 契约下同样不可取); - [ ] 是否位于 manifest 顶层(与
name、version平级,而不是嵌套在background等子对象内); - [ ] 是否与其他必填元数据字段(
name、version)共存,以满足最小合法清单要求; - [ ] 若同时声明
background,是否遵循 V3 的service_worker单文件写法,而非scripts+persistent的 V2 兼容模式。
常见错误与对应现象:
| 错误写法 | 现象 | 修复 |
|---|---|---|
"manifest_version": "3" |
类型不匹配,Codable 解码失败 | 去掉引号写成 3 |
"manifest_version": 2 |
校验抛出 invalidManifestVersion(2),扩展无法加载 |
升级为 3,并将后台脚本迁移到 service_worker |
| 缺少该字段 | 解码时缺少必填 key,清单整体解析失败 | 在顶层补充 "manifest_version": 3 |
"manifestVersion": 3 |
键名不匹配,无法映射到 manifestVersion 属性 |
改为下划线键名 |
小结
manifest_version 虽只是一个数字字段,却是整个 WebExtensions 清单体系的入口契约。在 iTerm2 的 WebExtensionsFramework 中,它经由 ExtensionManifest.swift 的 Int 属性与 CodingKeys 映射完成解码,再由 ManifestValidator.swift 的 validateManifestVersion 强制约束为 3,并以仓库内 test-extensions 与测试资源中的多份真实清单作为最佳实践参照。理解这一字段的"必填、数字、恒等于 3"三重属性,是在 iTerm2 乃至任何 WebExtensions 宿主中写出合法、可加载、可调试扩展清单的第一步。