fastOptJS链接错误清理后消失的原因排查：配置还是编码问题？

这种“执行./sbt fastOptJS报错，但clean后就正常”的问题在Scala.js项目里挺常见的，大多和增量编译的缓存机制、代码生成逻辑或者配置细节有关，下面是几个最可能的原因和对应的排查方向：

• 增量编译缓存未正确识别代码变更
  Scala.js的fastOptJS依赖sbt的增量编译来提升速度，它会缓存之前的编译结果。但如果你的代码发生了一些“非显性”的变更——比如修改了类的方法签名、删除/重命名了依赖的类，或者调整了父类的成员——增量编译可能没精准追踪到这些变化，导致旧缓存里的代码和新代码不兼容，出现“引用不存在的方法”错误。
  解决建议：

  • 可以尝试调整sbt的增量编译配置，比如在build.sbt中添加：

    incOptions := incOptions.value.withLogRecompileOnMacro(false)
    

    这个设置主要针对宏相关的缓存误判，如果你的项目用了宏，可能会有帮助。
  • 如果频繁出现这个问题，也可以考虑在编译前自动触发clean，但这会牺牲增量编译的速度，比如添加：

    fastOptJS := (fastOptJS dependsOn clean).value
    

    不过这是权宜之计，更推荐找到根本原因。

• 宏或动态代码生成的追踪失效
  如果项目里用到了自定义宏、Scala.js的JS互操作宏（比如@JSImport的复杂用法），或者其他动态代码生成工具，这些工具生成的代码往往是增量编译的“盲区”。当宏的逻辑变化、或者宏依赖的输入文件更新时，增量编译可能没触发代码的重新生成，导致旧的生成代码引用了已经不存在的方法。
  解决建议：

  • 确保代码生成任务和编译任务建立了正确的依赖关系，比如把代码生成的输出目录标记为sources in Compile的一部分，让sbt能追踪到生成文件的变化。
  • 对于宏模块，尽量把宏的实现和使用宏的代码分开在不同的子模块里，这样宏模块的变更能正确触发使用模块的重新编译。

• build.sbt配置的依赖或编译设置问题
  一些配置细节也可能导致这个问题：

  • 模块间的依赖关系配置错误：比如模块A依赖模块B，但你把依赖设置成了provided或者test，导致模块B的变更不会触发模块A的重新编译。
  • 启用了fork设置：如果fork in run := true，可能会导致进程间的缓存不同步，尤其是当你修改了代码后，fork的进程还在使用旧的编译结果。
    解决建议：
  • 检查build.sbt里的依赖配置，确保所有编译时依赖都用libraryDependencies += ... % "compile"。
  • 暂时关闭fork in run设置，看看问题是否消失，如果是，再调整fork的缓存相关参数。

• 编码中的隐性陷阱
  一些编码习惯也可能让增量编译“迷惑”：

  • 隐式转换或类型别名的变更：如果你修改了一个全局作用域的隐式转换签名，或者调整了类型别名的指向，依赖这些转换/别名的代码可能没被重新编译。
  • 同名类/方法的冲突：在不同文件里定义了同名的顶级类或方法，增量编译可能会混淆不同版本的代码。
  • JS互操作代码的修改：比如修改了@JSExport的方法名，或者@JSImport的模块路径，增量编译可能没正确更新对应的JS绑定代码。
    解决建议：
  • 尽量缩小隐式转换的作用域，避免全局隐式带来的追踪问题。
  • 避免在不同文件里定义同名的顶级成员，用包或者对象来隔离。
  • 修改JS互操作代码后，可以手动修改一下依赖该代码的文件（比如加个空格再保存），强制触发重新编译。

内容的提问来源于stack exchange，提问作者Gibberling Lard