Mill编译器中关于增量编译问题的分析与解决

在Scala生态系统中，Mill作为新一代构建工具，其增量编译机制与SBT有所不同。近期发现一个典型问题场景：当项目使用宏定义并配合typeCheckErrors进行编译时测试时，Mill编译器会抛出Failed to find name hashes异常，而同样的代码在SBT和Scala CLI中却能正常编译。

问题现象

在Mill 0.12.14版本中，当项目结构包含以下要素时会触发该问题：

1. 使用Scala 3.7.1编译器
2. 包含宏定义（通过scala.quoted实现）
3. 测试代码中使用scala.compiletime.testing.typeCheckErrors验证编译错误
4. 采用非标准文件布局（混合SBT/Maven布局与Mill默认布局）

错误表现为编译器无法找到测试代码生成的特殊包对象（$package类）的名称哈希值，导致增量编译过程中断。

技术背景

Mill的增量编译基于Zinc实现，但与SBT有以下关键差异：

1. 文件布局：Mill默认采用扁平化目录结构（src/下直接放scala文件），而SBT使用深层嵌套结构（src/main/scala/）
2. 类文件分析：Zinc在分析类文件依赖时需要维护名称哈希表，用于检测源代码变更
3. 宏处理：当涉及编译时宏展开时，编译器会生成额外的合成类

根本原因

问题源于项目布局与构建配置的不匹配：

1. 源代码采用SBT风格的src/main/scala/目录结构
2. 但build.sc中直接继承ScalaModule而非SbtModule
3. 测试代码与主代码混用同一模块，未明确分离

这种配置冲突导致：

• Mill的增量编译器无法正确定位生成的合成类文件
• 名称哈希表构建过程出现断层
• 最终在分析阶段无法找到$package类的哈希信息

解决方案

通过以下任一方式均可解决问题：

方案一：统一文件布局（推荐）

// build.sc
object internals extends ScalaModule {
  def scalaVersion = "3.7.1"
  // 将源文件移动到mill标准布局：src/internals/
}

方案二：显式声明SBT布局

// build.sc
object internals extends SbtModule {
  def scalaVersion = "3.7.1"
  
  object test extends SbtTests with TestModule.Utest
}

最佳实践建议

1. 布局一致性：明确选择Mill标准布局或SBT布局并保持一致
2. 模块分离：测试代码应放在独立的test模块中
3. 宏代码隔离：将宏实现放在单独的子模块，减少对增量编译的影响
4. 版本管理：保持Mill与Scala编译器版本的兼容性

深入理解

该问题揭示了构建工具的两个重要方面：

1. 增量编译机制：依赖于精确的类文件分析和哈希跟踪
2. 项目布局约定：不同构建工具对"标准"布局的理解差异可能导致微妙问题

对于跨构建工具的项目，建议在早期就明确布局规范，并在CI中增加多构建工具的验证环节，可以提前发现这类兼容性问题。