文件拖到新模块后能编译，CI 却报 00309001：DevEco Studio 26.0 跨模块重构怎么验收
DevEco Studio 26.0 优化了文件跨模块移动时的符号导入处理，移动进出模块后索引会相应更新。体验更顺，但自动改 import 不等于模块设计已经正确：本地默认大小写不敏感、相对路径越界或直接引用实现文件，都可能在 CI 的严格检查里暴露。官方 00309 错误码明确限制跨模块相对路径、绝对路径和大小写不一致。重构验收要从“红线消失”继续走到“依赖契约成立”。
验证边界：本文以文末当前华为官方资料为事实来源。应用侧判定与第二段断言已在本机 Node.js 环境执行；当前本机 SDK 为 API 24、没有 HDC 真机，也没有把模拟器或工具新增能力包装成已经完成 API 26 编译和真机验证。
把一个工具文件从 entry 移到 feature 模块
移动前记录 importGraph、moduleOwner、publicExports 和 caseSensitiveCheck；用 IDE 重构移动文件并接受 import 更新。本地编译后，在严格大小写和模块边界检查的 CI 中复跑。记录 unresolvedImports、outsideRelativeImports、absoluteImports 和 apiSurfaceDiff。若本地绿、CI 报 00309001/00309002/00309003，说明自动索引更新没有替你建立合法依赖。
案例一：相对路径穿过模块边界，本地索引仍能找到文件
这类引用破坏模块封装，官方错误明确禁止。应通过模块公开导出或合法依赖引用，不能把 ../../../ 当作快捷方式。
案例二：Index.ets 大小写在本地可用，严格检查环境失败
开启 caseSensitiveCheck 后，目录导入要求正确的 index 文件大小写，import 名称也要与实际文件一致。Windows 本地通过不能替代严格环境验证。
先画模块所有权，再移动文件
判断文件属于基础能力、业务特性还是页面实现。若多个模块使用，先设计公开接口与依赖方向；如果只为解决循环依赖而随手移动，自动 import 可能把错误结构固化得更隐蔽。
公开导出是契约，不是路径别名
消费者引用模块暴露的稳定符号，模块内部可以继续重构。验收时比较 apiSurfaceDiff，确保没有无意暴露内部类，也没有删除外部仍依赖的接口。
本地与 CI 使用同一严格规则
把 caseSensitiveCheck、模块越界和绝对路径检查放进提交前流程。移动后清理索引缓存不是验收，干净检出、重新安装依赖和完整构建才接近真实 CI。
为什么不能只看工具界面
工具提供的是观察、模拟或重构能力，应用仍要定义自己的成功信号。本文把每次操作都绑定到 scenarioId、artifactId 或 stateSnapshot，失败时保留输入、环境和读回结果。这样即使换设备、换构建或换开发者，也能复现同一问题，而不是依赖一句“我这里正常”。
证据如何进入持续集成
把本文的最小断言放入提交前检查：配置变化先做静态校验，模拟场景保存脚本与环境摘要，UI 状态保存前后快照，重构保存依赖图差异。工具报告只是附件；真正决定是否通过的是版本匹配、任务完成和失败信号。没有目标 API 26 环境时，结果必须标记为 host-only 或 source-reviewed，不能冒充平台实测。
可复用工程切片
type ImportEdge={fromModule:string;toModule:string;path:string;publicExport:boolean} function valid(e:ImportEdge){ if(e.path.match(/^[A-Za-z]:\\/))return false if(e.fromModule!==e.toModule&&!e.publicExport)return false return true }第一段保留目标工程需要的结构与字段，仍需在 DevEco Studio 26.0/API 26 环境验证。下面的主机断言只验证本文的应用侧规则。
function valid(e){if(/^[A-Za-z]:\\/.test(e.path))return false;return e.from===e.to||e.publicExport} if(valid({from:'entry',to:'feature',path:'../feature/a',publicExport:false}))throw new Error('跨模块实现路径未拦截'); if(!valid({from:'entry',to:'feature',path:'feature',publicExport:true}))throw new Error('公开契约被误拒');方案对比
| 方案 | 优点 | 风险 |
| 手工全文替换路径 | 直接 | 易漏别名与大小写 |
| 只信 IDE 自动更新 | 省事 | 不验证模块契约 |
| IDE 重构 + 依赖图 + 严格 CI | 可靠 | 需要维护公开导出 |
采用第三种，让 IDE 处理机械引用，让依赖图和 CI 判断架构是否合法。
交付物与检查表
移动前后 importGraph、公开导出差异、严格构建记录和 00309 错误清零报告。
- 没有相对路径跨模块。
- 没有绝对路径 import。
- 大小写与真实文件一致。
- 消费者只依赖公开导出。
- 干净环境完整构建通过。
自动重构解决“引用怎么跟着走”，模块验收回答“它该不该这样走”。两步都完成，跨模块移动才算结束。
当前官方资料
- DevEco Studio 26.0 新增特性
- ArkTS import 语法
- ArkTS 编译错误码 00309
- 工程级 build-profile
