做有网络/硬件依赖的 App，迟早会遇到这个矛盾：
开发期：没有真机麦克风、没有真实 API Key，也要能演示完整流程。所以需要一套假数据（我们叫 DevFixture / Fake 服务），最好还能一键切换 8 种预置场景。
上架时：Release 包里一行 Fake 代码都不能有。不只是"不会被执行"，而是物理上不存在——审核、安全扫描、以及你自己的良心，都要求这一点。
常见的两种"开关式"做法，在鸿蒙 ArkTS 上都给不了这个保证。这篇讲我们最终落地的第三种方案：物理文件切换（composition seam）。
1. 为什么 BuildProfile 开关和动态 import 都不够
方案 A：BuildProfile 字段 + if 分支（不够）
build-profile.json5可以给 debug/release 注入不同的构建字段：
"buildModeSet": [ { "name": "debug", "buildOption": { "arkOptions": { "buildProfileFields": { "ENABLE_DEV_FIXTURE": true } } } }, { "name": "release", "buildOption": { "arkOptions": { "buildProfileFields": { "ENABLE_DEV_FIXTURE": false } } } } ]然后代码里写：
import { createFakeAsr } from './service/fake/SpeakLabFakeAsr'; // ← 问题在这 if (BuildProfile.ENABLE_DEV_FIXTURE) { runtime = createFakeAsr(); } else { runtime = createRealAsr(); }逻辑上 Release 永远走 else 分支。但**import语句在文件顶部，是静态依赖**：ArkTS 编译会把所有被静态 import 的模块一并打进字节码。也就是说，Release HAP 里依然躺着完整的 Fake 实现，只是运行时不会走到。"不会执行"和"不存在"是两回事——前者要靠运行时永远不出错来保证，后者是编译器保证的。
方案 B：动态 import（也不够）
那把 import 换成动态的：
if (BuildProfile.ENABLE_DEV_FIXTURE) { const fake = await import('./service/fake/SpeakLabFakeAsr'); }方向对了，但实测下来，被动态 import 的模块依然会被打包进 HAP。动态 import 解决的是"加载时机"，不是"产物裁剪"。指望 Tree Shaking 把分支消除掉再顺手砍掉模块？这依赖编译器对BuildProfile.ENABLE_DEV_FIXTURE做常量折叠，属于把安全边界押在工具链的优化行为上——优化策略哪天变了，你的 Release 包里就悄悄多出一套假数据。
我们要的是一个不依赖任何优化行为的保证。结论：既然问题出在"这个文件被 import 了"，那就让 Release 构建时那个 import 语句根本不存在。
2. composition seam：一份接口，两份实现，构建前换掉文件
做法一句话：把"组装应用根运行时"这件事抽成一个 seam 模块，给它两份物理实现，构建前用脚本把对应的那份拷贝成活动文件。
entry/src/main/ets/common/composition/ ├── SpeakLabShellComposition.ets # 活动文件（AppShell 唯一 import 的） ├── SpeakLabShellComposition.debug.ets # Debug 模板：静态 import DevFixture └── SpeakLabShellComposition.release.ets # Release 模板：只 import 生产实现AppShell 只 import 活动文件：
import { createSpeakLabShellRuntime, ensureSpeakLabShellCompositionReady, SPEAKLAB_SHELL_BANNER } from '../common/composition/SpeakLabShellComposition';Release 模板：fail-closed，Fake 这个词根本不出现
Release 模板组装的是全生产路径：CoreSpeech ASR、ArkAgent AI 服务、系统权限 port、Preferences 设置、filesDir 历史：
// SpeakLabShellComposition.release.ets import { SpeakLabCoreSpeechAsrService } from '../asr/SpeakLabCoreSpeechAsrService'; import { SpeakLabProductionAiService } from '../ai/SpeakLabProductionAiService'; import { SpeakLabSystemMicrophonePermissionPort } from '../permission/SpeakLabSystemMicrophonePermissionPort'; // …没有任何 Fake / DevFixture import export function createSpeakLabShellRuntime(): SpeakLabAppRuntime { const asr = new SpeakLabCoreSpeechAsrService(); const aiService = new SpeakLabProductionAiService(coordinator, credential, store); // …组装并返回生产运行时 }注意它的设计姿态是fail-closed（缺什么就坏掉，而不是缺什么就用假的顶上）。比如 Ability context 还没就绪时，权限 port 不是返回一个假装的 GRANTED，而是一个永远报告 UNKNOWN 的实现：
class SpeakLabReleasePermissionUnavailablePort implements SpeakLabMicrophonePermissionPort { async check(): Promise<SpeakLabPermissionStatus> { return SpeakLabPermissionStatus.UNKNOWN; } // request / openSettings 同样 UNKNOWN }UI 层拿到 UNKNOWN 走"权限未就绪"的引导路径，而不是误以为自己有权限。Release 的每一个降级分支都必须"显式地坏"，这是这套方案能和假数据彻底切割的前提。
Debug 模板：同一个接口，静态装入全套夹具
Debug 模板导出完全相同的 API 表面，内部换成夹具工厂：
// SpeakLabShellComposition.debug.ets import { createSpeakLabDevFixtureRuntime, createSpeakLabDevFixtureRuntimeById, SPEAKLAB_DEV_FIXTURE_BANNER } from './SpeakLabDevFixtureComposition'; // 静态 import，故意的 export function createSpeakLabShellRuntime(): SpeakLabAppRuntime { return createSpeakLabDevFixtureRuntime(); } export function createSpeakLabShellRuntimeById(id: string): SpeakLabAppRuntime | null { return createSpeakLabDevFixtureRuntimeById(id); }注释里写得很直白：Static imports of DevFixture are intentional here。Debug 包就是要带全套假数据（8 个FAKE_*场景、明显的origin=FAKE审计横幅），静态 import 保证它确实在包里。两份模板实现同一组导出函数（createSpeakLabShellRuntime/createSpeakLabShellRuntimeById/ensureSpeakLabShellCompositionReady/ banner 常量……），签名严格对齐——对齐本身就是约束： seam 两侧的调用方无感知。
3. 切换脚本：拷贝 + grep 自检
切换由scripts/apply-shell-composition.sh完成，逻辑就是一行cp，但附带了自检：
TEMPLATE="$COMP_DIR/SpeakLabShellComposition.${MODE}.ets" cp "$TEMPLATE" "$ACTIVE" # Sanity: Release must not mention DevFixture; Debug must. if [ "$MODE" = "release" ]; then if grep -q 'SpeakLabDevFixtureComposition\|service/fake' "$ACTIVE"; then echo "apply-shell-composition: FAILED — Release seam still references DevFixture/fake" >&2 exit 1 fi fi拷贝之后立刻 grep 验证：Release 活动文件里出现DevFixture或service/fake字样就直接失败退出。这个检查看起来冗余（文件刚刚是你自己拷的），但它把"Release seam 干净"从约定变成了每次构建都强制执行的不变式——哪天有人往 release 模板里 import 了假数据调试，脚本当场拦住。
构建脚本build-entry-hap.sh把切换和构建串成原子操作，顺序不可颠倒：
bash "$SCRIPT_DIR/apply-shell-composition.sh" "$MODE" # 先切 seam hvigorw clean --no-daemon # 再 clean hvigorw --mode module -p product=default -p module=entry@default \ -p "buildMode=${MODE}" assembleHap --no-daemon # 最后构建只设buildMode而不切 seam 是不完整的——buildMode 只改编译参数，不改源码。这也是为什么团队纪律是"构建 HAP 只能走build-entry-hap.sh，不许手敲 hvigorw"。
4. 双 HAP 审计：把"零 Fake"验证到字节码层面
seam 干净只是源码层面的保证。最终交付前，还有一个check-release-fixture-isolation.sh，同时吃 Release 和 Debug 两个签名 HAP，解包审计字节码：
Release HAP：不得出现 DevFixture / Fake 相关符号；
Debug HAP：必须出现（反向验证，防止"两边都没了"的假阳性——Debug 都没了说明审计规则本身失效）。
这一正一反的设计值得多说一句。只做"Release 里没有"的检查，遇到检查脚本写错了（比如搜的路径不对，永远搜不到）会一路绿灯。加上"Debug 里必须有"，检查机制本身也被检查了。这和后面 B18 会讲的 mutation 测试是同一个思想：验证手段自身也要被验证。
5. 这套方案的代价与应对
诚实地说，物理切换不是没有成本：
工作区会被脚本改动。
SpeakLabShellComposition.ets是生成物，切到 debug 构建后git status会显示它被修改。应对：活动文件也提交（与 release 模板保持一致的版本），任何时候仓库里的默认状态都是 Release seam；构建脚本负责临时换掉它。开发者改 Release 路径时，同步编辑模板和活动文件两处（文件头注释里写死了这个要求）。两份模板要保持 API 对齐。Debug 加了新接缝函数，Release 也得有对应签名（哪怕是空实现或 fail-closed 实现）。好在 seam 函数只有寥寥几个，且 Hypium 测试会同时编译两份，签名漂移编译期就炸。
多了一步"构建前仪式"。用包装脚本收口后，对开发者是透明的。
换来的是：任何时刻，给审核、给客户、给安全同事的 Release 包，都可以拍着胸脯说"里面没有一行调试代码"，并且这句话有脚本、有审计、有双 HAP 证据支撑。
6. 小结
BuildProfile 分支和动态 import 都只控制"执行"，不控制"打包"；要 Release 零 Fake，必须让 Fake在源码层面就不被 import。
composition seam = 一份接口、两份物理模板、构建前
cp切换 + grep 自检。Release 模板按 fail-closed 设计：缺依赖就显式降级（UNKNOWN），绝不用假数据顶包。
双 HAP 审计一正一反：Release 必须没有，Debug 必须有——检查机制本身也被检查。
纪律：
buildMode不等于隔离，构建只走build-entry-hap.sh。
