workerd 兼容性标志Compatibility Flags查询指南使用 compat-flag 命令定位 API 行为开关【免费下载链接】workerdThe JavaScript / Wasm runtime that powers Cloudflare Workers项目地址: https://gitcode.com/GitHub_Trending/wo/workerd导读兼容性标志Compatibility Flags是 workerdCloudflare Workers 的开源运行时中控制 API 行为变更的核心机制它让破坏性变更可以借助兼容日期compatibility date渐进式铺开。本指南围绕仓库中.opencode/commands/compat-flag.md定义的compat-flag命令展开无参数时它汇总列出全部标志带参数时它能精确定位单个标志的启用/禁用名称、默认日期、C 使用点与测试用例。读完本文你将掌握用compat-flag命令高效检索 workerd 标志体系的方法并理解标志背后的 Capn Proto 定义与注解机制。一、compat-flag 命令是什么compat-flag是仓库在.opencode/commands/compat-flag.md中定义的一条 OpenCode 命令元数据如下descriptionLook up a compatibility flag, or list all flags if no argument given查询某个兼容性标志若无参数则列出全部标志subtasktrue说明它适合作为子任务被自动调用命令的行为完全由参数决定形成两条独立的分支调用方式行为compat-flag无参数或空白参数汇总列出全部兼容性标志按类别分组输出表格并给出总数compat-flag flag_name带参数查询单个标志的元数据、C 使用点、测试用例与注解这套检索流程与兼容性标志的数据源头 —— compatibility-date.capnp共 1675 行定义 189 个带$compatEnableFlag注解的字段以及 compatibility-date.c —— 一一对应因此命令的输出可以直接回溯到源码。二、无参数列出全部兼容性标志当命令不携带任何参数空串或空白时执行流程为调用compat-date-at工具不带参数获取全部标志的启用日期、分类与注解。文档特别强调这比手动阅读 capnp 文件更快、更准确对每个标志从 compatibility-date.capnp 中对应字段上方的注释块提取一句话摘要按类别streams、nodejs、containers、general 等分组输出汇总表格并统计标志总数。汇总表格的标准格式如下FlagEnable dateDescriptionflag_name2025-01-15Brief description2.1 类别是如何划分的从 capnp 源码看标志并没有显式的类别字段类别来自注释与命名约定。例如streams 类streams_byob_reader_detaches_buffer5、streams_enable_constructors62022-11-30 起默认、fixup-transform-stream-backpressure682024-12-16 起默认见 compatibility-date.capnpnodejs 类nodejs_compat_populate_process_env76、enable_nodejs_process_v297、enable_nodejs_fs_module105、enable_nodejs_http2_module112等多数通过$impliedByAfterDate(name nodeJsCompat, ...)与nodejs_compat联动containers 类containers_pid_namespace160等以containers_为前缀的标志general 类其余未归类的通用 API 行为标志如url_standard10、global_navigator11、minimal_subrequests8。2.2 总数的统计口径命令要求输出标志的总数。以当前仓库为准grep -c compatEnableFlag src/workerd/io/compatibility-date.capnp的结果为189即当前定义了 189 个可通过compatEnableFlag名称控制的标志字段字段序号从0到189。其中相当一部分标注为obsoleteN例如obsolete3、obsolete14、obsolete63、obsolete66它们仅保留以兼容历史配置实际已无行为影响。三、带参数查询单个兼容性标志当传入具体标志名如compat-flag text_decoder_replace_surrogates时命令执行五步检索流程。3.1 获取标志元数据调用compat-date-at工具并传入flag: argument获得该标志的启用名称enable name与禁用名称disable name启用日期enable date注解annotations随后阅读 capnp 源码中对应字段的注释块。需提取的元数据清单元数据项说明来源字段名与序号如textDecoderReplaceSurrogates 159capnp 字段声明$compatEnableFlag名称启用新行为的标志名capnp 注解$compatDisableFlag名称若有在新行为成为默认后退出旧行为的标志名capnp 注解$compatEnableDate若有之后该行为对所有 Worker 默认生效的日期capnp 注解$experimental是否需--experimental才能使用capnp 注解注释块描述标志的变更内容与动机字段上方注释3.2 查找 C 使用点在源码中检索自动生成的 getter如getTextDecoderReplaceSurrogates()或 snake_case 标志名grep -rn getTextDecoderReplaceSurrogates\|text_decoder_replace_surrogates src/以该标志为例检索结果确认了使用点存在于 src/workerd/api/encoding.cif (slice.size() 0 || !FeatureFlags::get(js).getTextDecoderReplaceSurrogates()) {FeatureFlags类定义在 src/workerd/io/features.hgetter 名称由 capnp 字段名的 camelCase 形式加get前缀、首字母大写派生而来。也就是说字段textDecoderReplaceSurrogates直接映射为getTextDecoderReplaceSurrogates()。3.3 查找测试用例用 snake_case 标志名在.wd-test与测试.js/.ts文件中搜索grep -rn text_decoder_replace_surrogates src/ \ --include*.wd-test --include*-test.js --include*-test.ts.wd-test是 workerd 的测试描述文件Capn Proto 格式测试中可以在worker.compatibilityFlags列表里显式列出要启用的标志。3.4 输出结构查询结果的输出模板Flag启用名称 / 禁用名称Enable date具体日期或 not set (must be explicitly enabled)未设日期必须显式启用Descriptioncapnp 注释块内容Usage sitesC 中检查该标志的位置file:line列表Tests覆盖该标志的测试位置file:line列表Annotationsexperimental、neededByFl、impliedByAfterDate等若未找到则提示检查拼写并列出名称相似的标志3.5 完整示例text_decoder_replace_surrogates综合源码该标志的完整检索结果如下Flagtext_decoder_replace_surrogates/disable_text_decoder_replace_surrogatesEnable date2026-02-24见 compatibility-date.capnpDescription启用后UTF-16LE 的 TextDecoder 会按规范要求将孤立的代理项lone surrogates替换为 UFFFDUnicode 替换字符。此前孤立代理项会原样通过产生非良构non-well-formed字符串。Annotations$impliedByAfterDate(name pedanticWpt, date 2026-02-24)—— 即 2026-02-24 之后只要pedantic_wpt被启用本标志也随之启用。Usage sitessrc/workerd/api/encoding.c 的getTextDecoderReplaceSurrogates()检查。Tests在src/workerd/下按上述 grep 命令检索即可定位对应.wd-test用例。四、兼容性标志系统的底层原理4.1 数据模型Capn Proto 结构体与注解所有标志集中在 compatibility-date.capnp 的CompatibilityFlags结构体中文件头注释明确写道Flags that change the basic behavior of the runtime API, especially for backwards-compatibility with old bugs.每个布尔字段通过注解声明自己的剧本。文件内定义了全部注解注解作用语义要点$compatEnableFlag(name)启用新行为的标志名建议所有特性先定义 enable-flag测试完成后再分配日期$compatDisableFlag(name)禁用标志名供需要长期保留某个 bug 行为的 Worker 使用应尽量为多数特性定义$compatEnableDate(YYYY-MM-DD)此日期后默认启用日期字符串格式如2021-05-17$compatEnableAllDates所有日期均默认启用几乎总是会破坏向后兼容慎用$experimental需--experimental才能使用不受 Workers 常规向后兼容承诺约束可能随时变更或移除$neededByFl需要向 FL 层传播FL 指 Cloudflare 的 HTTP 代理栈除brotliContentEncoding外此类标志在 workerd 独立运行时外无效果$impliedByAfterDate(name, date)指定日期后被另一标志隐含启用用于标志间的联动与归并$pythonSnapshotRelease标记影响 Python 内存快照引入 Python Worker 快照破坏性变更时使用4.2 日期机制与最大兼容日期标志的默认状态由 Worker 的compatibilityDate与各标志的$compatEnableDate比较决定日期之后新行为对所有 Worker 生效但显式设置compatibilityFlags可以覆盖日期推断。仓库在 src/workerd/io/maximum-compatibility-date.txt 维护当前最新的兼容日期本仓库为2026-09-15它与 src/workerd/io/compatibility-date.c 一起决定了测试中all-compat-flags变体所代表的最新行为全集。4.3 标志如何被消费decompile 与 gettersrc/workerd/io/compatibility-date.c 中的decompileFlags()把已启用的布尔字段反编译回 enable-flag 名称字符串数组kj::Arraykj::StringPtr decompileFlags( CompatibilityFlags::Reader input, kj::ArrayPtrconst ParsedField fieldTable) { kj::Vectorkj::StringPtr enableFlags(fieldTable.size()); for (auto field: fieldTable) { if (capnp::toDynamic(input).get(field.field).asbool()) { enableFlags.add(field.enableFlag); } } return enableFlags.releaseAsArray(); }decompileCompatibilityFlagsForFl()只遍历带$neededByFl注解的字段onlyNeededByFltrue供 FL 层在子请求上传播decompileCompatibilityFlags()则输出全部已启用标志。运行时层面C 代码通过FeatureFlags::get(js).getXxx()读取标志JSG API 资源类则可以在JSG_RESOURCE_TYPE中按标志动态挂载方法详见下文。五、标志的完整生命周期从定义到验证compat-flag命令面向查询而标志的新增遵循 adding-a-compatibility-flag.md 六步流程。理解这两份文档的配合才能完整掌握 workerd 的兼容性治理体系。5.1 在 capnp 中声明新标志在 compatibility-date.capnp 的CompatibilityFlags结构体末尾追加字段myNewBehavior NEXT_ORDINAL :Bool $compatEnableFlag(my_new_behavior) $compatDisableFlag(no_my_new_behavior) $compatEnableDate(2026-03-15); # Description of what this flag changes and why. # Include context about the old behavior and what the new behavior fixes.字段名用 camelCase直接派生 C getter标志名用 snake_case注释块是必需的内部文档。5.2 在 C 中读取标志普通代码路径if (FeatureFlags::get(js).getMyNewBehavior()) { // New behavior } else { // Old behavior }JSG API 资源类中按标志暴露方法JSG_RESOURCE_TYPE(MyApi, workerd::CompatibilityFlags::Reader flags) { if (flags.getMyNewBehavior()) { JSG_METHOD(newMethod); } }5.3 测试变体系统workerd 的测试变体命名约定与日期机制直接挂钩test-name使用最老兼容日期2000-01-01测试旧行为test-nameall-compat-flags使用最新兼容日期2999-12-31测试新行为在.wd-test文件中可显式设置标志注意此类测试不应再包含compatibilityDate字段const unitTests :Workerd.Config ( services [( name my-test, worker ( modules [(name worker, esModule embed my-test.js)], compatibilityFlags [my_new_behavior], ), )], );5.4 构建与验证命令# 构建以验证 capnp schema 可编译 just build # 运行特定测试旧行为 just stream-test //src/workerd/api/tests:my-test # 启用全部兼容标志运行新行为 just stream-test //src/workerd/api/tests:my-testall-compat-flags # 验证标志注册是否合法 just stream-test //src/workerd/io:compatibility-date-test标志的启用日期到达前还必须在 cloudflare-docs 仓库的src/content/compatibility-flags/下补充面向用户的文档说明行为变更、默认日期、opt-in/opt-out 方式与迁移指引详见 docs/api-updates.md。六、典型应用场景排查 API 行为差异某段代码在旧日期下正常、新日期下异常用compat-flag 名称找到对应标志、默认日期与使用点即可判断是否被兼容日期隐式切换了行为。评估破坏性变更影响面无参数调用compat-flag获得全量表格按类别过滤出与自身业务相关的 streams / nodejs 类标志逐个确认启用日期。为测试定位标志从输出中的 Tests 一节直接拿到.wd-test与测试 JS 文件路径快速复用既有覆盖。理解标志联动impliedByAfterDate让nodejs_compat、python_workers等总开关在指定日期后级联启用一系列子标志查询单个子标志时留意这类注解即可还原完整依赖链。七、注意事项与边界$experimental标志只能在 workerd 以--experimental运行时使用不承诺向后兼容Cloudflare 多租户生产环境仅限内部测试账号。示例包括typescript_strip_types111、allow_insecure_inefficient_logged_eval113等。$compatEnableAllDates如r2_public_beta_bindings13那样所有日期默认启用几乎必然破坏向后兼容compatEnableDate未设时查询结果会标注 must be explicitly enabled。废弃标志obsoleteN字段与无效果但保留以通过配置校验的标志如workflows_bindings_rpc、wasm_memory_discard仍会计入总数解读表格时需结合注释区分。neededByFl仅对 Cloudflare 内部生效除brotliContentEncoding外此类标志在独立部署的 workerd 中没有行为效果查询时可据此判断该标志是否与我的自托管场景相关。八、进一步阅读compat-flag 命令定义本文讲解的检索命令本体compatibility-date.capnp全部 189 个标志的权威定义与注解compatibility-date.c标志反编译与 FL 传播实现maximum-compatibility-date.txt当前最新兼容日期adding-a-compatibility-flag.md新增标志的六步操作指南api-updates.mdAPI 与标志的文档化流程【免费下载链接】workerdThe JavaScript / Wasm runtime that powers Cloudflare Workers项目地址: https://gitcode.com/GitHub_Trending/wo/workerd创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考