AWS SAM CLI 构建过程中的 Unicode 解码错误分析与解决

问题现象

在使用 AWS SAM CLI 进行项目构建时，用户遇到了一个 Unicode 解码错误。具体表现为执行 sam build --no-cached --debug 命令时，系统抛出错误信息："'utf-8' codec can't decode byte 0x95 in position 147: invalid start byte"。

错误背景

这个错误发生在 Windows 10 操作系统环境下，使用的 SAM CLI 版本为 1.125.0。从错误堆栈来看，问题出现在 SAM CLI 尝试读取构建缓存文件时，遇到了非 UTF-8 编码的字符，导致解码失败。

根本原因分析

1. 缓存文件损坏：最可能的原因是 .aws-sam 目录下的构建缓存文件被损坏或包含了非 UTF-8 编码的内容。这种情况可能发生在：

   • 构建过程被意外中断
   • 手动修改了缓存文件
   • 其他工具修改了缓存文件内容

2. 编码问题：Windows 系统有时会使用非 UTF-8 编码保存文件，而 SAM CLI 默认使用 UTF-8 编码读取文件，导致解码失败。

3. 多工具干扰：如果同时使用其他 AWS 工具或第三方工具操作同一项目，可能会意外修改缓存文件格式。

解决方案

1. 清除构建缓存：

   • 删除项目根目录下的 .aws-sam 文件夹
   • 重新运行 sam build 命令

2. 预防措施：

   • 避免手动修改 .aws-sam 目录下的文件
   • 确保构建过程完整完成，不要中途强制终止
   • 如果使用多个工具操作同一项目，确保它们之间的兼容性

技术细节

当 SAM CLI 执行构建时，会在 .aws-sam 目录下创建和维护一个构建图（Build Graph），用于跟踪构建状态和依赖关系。这个构建图以文件形式存储，默认使用 UTF-8 编码。当文件内容被意外修改或损坏时，就会导致解码错误。

最佳实践建议

1. 定期清理：在遇到构建问题时，首先尝试清理 .aws-sam 目录。
2. 版本控制：不要将 .aws-sam 目录纳入版本控制系统。
3. 环境隔离：为不同项目使用独立的环境，避免工具间的相互干扰。
4. 错误诊断：遇到类似编码错误时，检查最近是否有工具或操作可能修改了构建缓存。

总结

Unicode 解码错误在 AWS SAM CLI 构建过程中虽然不常见，但通常有明确的解决方法。理解 SAM CLI 的构建缓存机制有助于快速定位和解决这类问题。保持构建环境的整洁和一致性是预防此类问题的关键。