- 编程语言
- 编译器
- 语言运行时
- 标准库
- 开发工具
【免费下载链接】sdk
The Dart SDK, including the VM, JS and Wasm compilers, analysis, core libraries, and more.
pkg/dwds/test/frontend_server_common/是 DWDS（Dart Web Developer Service）测试套件中一套以“常驻前端服务器（frontend server）编译器”为核心的 Web 测试基础设施，其代码源自对 Flutter tools 相关模块的编辑复制。本文以该目录下 CHANGELOG-legacy.md 的版本记录为主线，逐条还原每次变更背后的技术动机，并结合仓库内frontend_server_client.dart、bootstrap.dart、devfs.dart、resident_runner.dart等源码，说明前端服务器客户端的启动方式、stdin/stdout 编译协议、DDC 库束（Library Bundle）引导以及热重启所需reloaded_sources.json的生成机制。读完本文，你将能读懂这套测试基座的架构脉络，并掌握各版本变更对应的具体代码位置与工作原理。
这套代码是什么：从 Flutter 复制而来的前端服务器测试基座
README.md 明确指出：该目录下的代码是 Flutter 代码的编辑副本，用于搭建前端服务器以及与 Chrome、DWDS 通信所需的组件，包括：
- 前端服务器客户端（frontend server client）
- Web runner（web runner）
- 开发文件系统（dev fs）
- 资产服务器（asset server）
其最终目标是与 Flutter 共享这套代码以实现更好的集成。目录内现包含frontend_server_client.dart、bootstrap.dart、devfs.dart、resident_runner.dart、asset_server.dart、utilities.dart、uuid.dart等实现文件，以及本篇文章解读的版本历史文件。
CHANGELOG-legacy.md 记录了该测试基座从 0.1.0 到 0.2.3-wip 的完整演进，恰好覆盖了从“初始版本”到“支持 DDC 库束格式引导、共享热重启条目逻辑”的成熟过程。虽然变更日志本身十分简练，但每一条都对应着仓库中可验证的具体实现，下面按版本逐一展开。
版本时间线总览
| 版本 | 关键变更 | 对应实现要点 |
|---|---|---|
| 0.1.0 | 初始版本 | 从 Flutter tools 复制并适配 DWDS 测试 |
| 0.1.1 | 移除死代码 | 清理不再需要的功能（如暂不支持热重载） |
| 0.2.0 | 迁移到空安全（null safety） | 源码全面使用String?、Completer<CompilerOutput?>等空安全语法 |
| 0.2.1 | 不再传递-debugger-module-names标志 | useDebuggerModuleNames变为条件参数 |
| 0.2.2 | 从 Dart SDK 内置 AOT 快照启动前端服务器 | 使用sdkLayout.frontendServerSnapshotPath |
| 0.2.3-wip | SDK 约束更新至^3.10.0；DDC 库束引导代码；compileExpression*Request增加scriptUri；新增createReloadedSourceEntry | 见下文逐条解读 |
0.1.0 与 0.1.1：起点与清理
0.1.0 是初始版本，代码脱胎于 Flutter tools。从源码中的注释可以确认这一点：frontend_server_client.dart 开头即注明"Note: this is a copy from flutter tools, updated to work with dwds tests"，resident_runner.dart 同样注明这是 Flutter 代码的副本，并且“移除了一些功能（暂不支持热重载）”。
0.1.1 的“移除死代码”正对应上述清理工作。该测试基座的职责边界由此固定为四块：负责与前端服务器进程通信的ResidentCompiler、负责生成浏览器引导脚本的bootstrap.dart、负责管理虚拟文件系统与资产发布的WebDevFS/TestAssetServer，以及统筹编译流程的ResidentWebRunner。
0.2.0：空安全迁移
0.2.0 将整个测试基座迁移到 Dart 空安全。这一变更贯穿所有源码文件：
- frontend_server_client.dart 中大量可空字段，如
Completer<CompilerOutput?>、String? scriptUri、bool? isStatic、String? klass； - bootstrap.dart 中
generateMainModule({required String entrypoint})等函数均使用required命名参数； null还被用作编译失败的信号，例如ResidentCompiler._compileExpression在服务器尚未启动时直接return null（frontend_server_client.dart），调用方TestExpressionCompiler.compileExpressionToJs在收到null时抛出Exception('Failed to compile $expression')（L697-L707）。
空安全迁移与同期的 Dart SDK 生态步调一致——独立的package:frontend_server_client（现已发布到 pub，源码位于 pkg/frontend_server_client）也在其 CHANGELOG.md 中记录了 2.0.0 的“Support null safety”。
0.2.1：不再传递-debugger-module-names标志
0.2.1 的原文是“Doe not pass-debugger-module-namesflag to the frontend server.”（原文中的 "Doe" 为 "Does" 之笔误）。从源码结构看，这一变更并没有彻底删除该能力，而是把它收敛为一个可选项。
在 frontend_server_client.dart 的启动参数构造逻辑中：
if (useDebuggerModuleNames) '--debugger-module-names',--debugger-module-names只在useDebuggerModuleNames为真时才加入命令行参数。该开关由 resident_runner.dart 在构造ResidentCompiler时从packageUriMapper.useDebuggerModuleNames传入。也就是说，默认情况下测试不再向前端服务器传递该标志，避免调试模块命名带来的额外开销或干扰，仅在需要时开启。
0.2.2：从 Dart SDK 内置 AOT 快照启动前端服务器
0.2.2 是一次重要的启动方式变更：不再依赖外部编译环境，而是直接从 Dart SDK 随附的 AOT 快照启动前端服务器。
在 DWDS 测试版客户端中，ResidentCompiler._compile通过sdkLayout.frontendServerSnapshotPath取得快照路径，并用sdkLayout.dartAotRuntimePath（即dartaotruntime可执行文件）拉起进程，随后依次追加--sdk-root、--incremental、--target=dartdevc、--output-dill、--packages、--filesystem-root、--filesystem-scheme、--platform等参数（frontend_server_client.dart#L389-L427）。
这一演进在独立包 pkg/frontend_server_client 中体现得更为完整：其FrontendServerClient.start默认寻找 SDK 内bin/snapshots/frontend_server_aot.dart.snapshot，并使用bin/dartaotruntime运行（lib/src/frontend_server_client.dart#L108-L159）；只有显式传入frontendServerPath时才改用dart可执行文件启动，此时还可配合debug: true以--observe模式运行以便调试器附着（L121-L133）。同时，若省略frontendServerPath却将debug置为 true，start会抛出ArgumentError（L134-L140）。该包自己的 CHANGELOG.md 在 4.0.0 中也记载了同样的变更："By default, start the frontend server from the AOT snapshot shipped in the Dart SDK."，并在 4.0.1-wip 中进一步支持“从独立 CLI 可执行文件运行并尊重sdkRoot”。
0.2.3-wip：四条关键变更逐条解读
SDK 约束收紧至^3.10.0
0.2.3-wip 将 Dart SDK 约束更新为^3.10.0。这与仓库中 pkg/frontend_server_client/pubspec.yaml 的environment: sdk: ^3.10.0-0.0.dev相印证。值得注意的是，package:frontend_server_client的 README.md 明确阐述了其 SDK 版本策略：它会对 SDK 保持相对紧的上限约束，因为frontend_server二进制本身可能发生破坏性变更；具体规则是“版本上限低于最新稳定 SDK 的下一个 minor 版本”，从而使frontend_server的破坏性变更只能随 minor SDK 版本发布，包在每次新稳定 SDK 发布后都需要重新发布以获得合法版本解析。
为 DDC Library Bundle 格式增加引导代码
这一条对应 bootstrap.dart 中新增的 DDC 库束引导族函数：
generateDDCLibraryBundleBootstrapScript({required ddcModuleLoaderUrl, required mapperUrl, required entrypoint, required bootstrapUrl})（L387-L532）：与既有generateDDCBootstrapScript类似，负责注入 base URL 探测脚本与$dartCreateScript加载器，随后通过dart_library模块加载dart_sdk.js与引导模块，并安装window.$dartReloadModifiedModules以支持热重启时按模块增量替换脚本；generateDDCLibraryBundleMainModule({required entrypoint, required onLoadEndBootstrap})（L536-L569）：生成库束模式下的主模块，它把dartDevEmbedder.runMain(appName, {})挂到window.$onLoadEndCallback，等待所有脚本加载完成后才真正执行 main；generateDDCLibraryBundleOnLoadEndBootstrap()（L571-L573）：返回触发加载结束回调的一行脚本。
这套引导代码是 DWDS 支持 DDC“库束”模块系统（library bundle）测试的基础，bootstrap.dart中对应的入口模块由 devfs.dart 依据ddcModuleFormat分发写入（ModuleFormat.ddc与ModuleFormat.amd分支分别生成不同引导脚本）。
compileExpression*Request增加scriptUri
0.2.3-wip 为表达式编译请求统一加入了scriptUri字段，涉及ResidentCompiler中的两类请求：
_CompileExpressionRequest（frontend_server_client.dart#L199-L222）新增String? scriptUri字段，对应调试器中在指定库/脚本上下文中求值表达式的场景；_CompileExpressionToJsRequest（L224-L249）同样携带String scriptUri，并在_compileExpressionToJs中把scriptUri、line、column等一起序列化为JSON_INPUT协议消息（L569-L584）：
server.stdin.writeln('JSON_INPUT'); server.stdin.writeln( json.encode({ 'type': 'COMPILE_EXPRESSION_JS', 'data': { 'expression': request.expression, 'libraryUri': request.libraryUri, 'scriptUri': request.scriptUri, 'line': request.line, 'column': request.column, 'jsModules': request.jsModules, 'jsFrameValues': request.jsFrameValues, 'moduleName': request.moduleName, }, }), );TestExpressionCompiler.compileExpressionToJs的签名中也包含scriptUri（L675-L708），说明该参数贯穿了 DWDS 调试表达式编译的完整调用链，用于精确定位表达式所属的源码位置。
createReloadedSourceEntry与reloaded_sources.json条目的共享
最后一条变更把“构造reloaded_sources.json条目”的逻辑抽取为静态方法，以便在测试基座内共享。其实现位于 devfs.dart：
static Map<String, Object> createReloadedSourceEntry({ required String src, required String module, required List<String> libraries, }) => {'src': src, 'module': module, 'libraries': libraries};而reloaded_sources.json的完整写盘逻辑在writeReloadedSources（L265-L286）中：对每个需要重载的模块，读取其.metadata中记录的ModuleMetadata，提取库名列表，调用createReloadedSourceEntry生成条目，最后写入固定路径reloaded_sources.json（常量reloadedSourcesFileName，L240）。
该文件的作用由 devfs.dart 的文档注释说明：它列出热重启/热重载时需要重新加载的模块，每个条目包含三个字段——src（含 DDC 库束的文件路径）、module（该库束的模块名）、libraries（编译进该库束的库名数组）。在 DDC 库束模式下，bootstrap.dart 中generateDDCLibraryBundleBootstrapScript的window.$dartReloadModifiedModules正是消费这类“模块/源文件”信息来完成增量替换。仓库 pkg/dwds/CHANGELOG.md 中还记载了后续演进："Report errors when an empty reloaded_sources.json is seen in the DDC Library Bundle module system"，说明这套共享逻辑成为 DWDS 主项目持续依赖的测试设施。
在编译流程中，devfs.dart的update方法会在首次启动时写入空的reloaded_sources.json（'[]'，L178），编译失败时删除该文件（L195），仅在增量编译成功后重新写入需要重载的模块列表。
串联起来：一次完整的测试编译流程
综合上述各版本演进，resident_runner.dart 中的ResidentWebRunner把整条链路串起来：run()首次启动时创建WebDevFS与ResidentCompiler，触发初始编译并accept()结果（L70-L102）；rerun()在热重启时通过ProjectFileInvalidator找出失效文件，交由WebDevFS.update完成增量编译与资产发布（L104-L148）。与此同时，ResidentCompiler内部通过_CompilationRequest队列保证“同一时刻只处理一个编译请求”（frontend_server_client.dart#L372-L387），并通过 UUID 边界键解析 stdout 上的编译结果、依赖增删（+/-前缀）与诊断信息（L60-L148），最终由TestAssetServer（asset_server.dart）以内存缓存方式对外提供 JS、sourcemap、metadata 与静态资产。
小结
从 0.1.0 到 0.2.3-wip，frontend_server_common走完了“从 Flutter 复制、清理死代码、迁移空安全、调整调试标志、改用 SDK AOT 快照启动、支持 DDC 库束引导并共享热重启条目逻辑”的完整演进路径。这份 changelog 虽然只有寥寥数行，却精确映射了仓库中可逐行验证的实现：bootstrap.dart的引导脚本族、devfs.dart的createReloadedSourceEntry/writeReloadedSources、frontend_server_client.dart的scriptUri与条件化--debugger-module-names、以及独立包 pkg/frontend_server_client 的 AOT 快照启动策略。对于希望理解 DWDS 测试如何驱动前端服务器增量编译、如何在浏览器中引导 DDC 模块、以及如何为热重启准备模块清单的读者，这份 changelog 连同上述源码是最直接的索引。
- 编程语言
- 编译器
- 语言运行时
- 标准库
- 开发工具
【免费下载链接】sdk
The Dart SDK, including the VM, JS and Wasm compilers, analysis, core libraries, and more.
相关推荐
从 CHANGELOG 看 @typespec/http-server-js：TypeSpec HTTP 服务端代码生成器的能力演进与实现原理
从 CHANGELOG 看 @typespec/http server js：TypeSpec HTTP 服务端代码生成器的能力演进与实现原理 @typespe
编程语言编译器后端Firefox Send 演进史：从 CHANGELOG 解读 Mozilla 端到端加密文件分享服务的架构变迁
Firefox Send 演进史：从 CHANGELOG 解读 Mozilla 端到端加密文件分享服务的架构变迁 本文以仓库根目录 CHANGELOG.md h
后端前端KubeSphere 测试基座：Ginkgo v2 版本演进与关键特性深度解读
KubeSphere 测试基座：Ginkgo v2 版本演进与关键特性深度解读 KubeSphere 仓库通过 go.mod 将 Ginkgo v2 锁定在 v
桌面应用即时通讯
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
