Docker 故障排除

本页面提供了生成器生成的 Docker 构建可能遇到的问题的故障排除指南。有关它们遵循的模式的背景信息，请参阅 Docker 打包指南。

跨平台构建

诸如 ts#strands-agent、py#strands-agent、ts#mcp-server 和 py#mcp-server 等生成器为 linux/arm64 (Graviton) 生成镜像，无论主机架构如何。在 x86_64 主机上构建 arm64 镜像——或在 Apple Silicon 上构建 amd64 镜像——需要本地 Docker 安装支持多平台构建。

如果未设置多平台构建，症状取决于 Dockerfile：

Dockerfile 有 RUN 步骤（TypeScript 生成器为不可打包的依赖项 RUN npm install）：构建中途失败，显示
Terminal window
```
exec /bin/sh: exec format error
```
Dockerfile 仅使用 COPY（Python 生成器）：构建成功，但稍后 docker run 失败，显示
Terminal window
```
exec /usr/local/bin/python: exec format error
```
基础镜像不适用于目标平台：构建在 FROM 步骤失败，显示 no match for platform in manifest。

启用多平台构建

Docker Desktop（Mac / Windows / Linux）默认启用了 QEMU 模拟——通常不需要额外设置。

Linux 主机（包括 CI 运行器）需要向内核注册 QEMU binfmt 处理程序。每台机器安装一次：

docker run --privileged --rm tonistiigi/binfmt --install all

验证支持的平台是否与您的项目目标匹配：

docker buildx inspect --bootstrap

Platforms: 行应包含 linux/arm64。

模拟架构上的慢速构建

在 x86_64 主机上构建 arm64 镜像（或反之）使用 QEMU 模拟每条指令，这可能比原生构建慢许多倍。生成器通过在 Dockerfile 之外进行依赖项解析来缓解这一问题——请参阅 Docker 打包。如果您仍然看到缓慢的 Docker 构建：

确保您通过 Nx 运行 bundle / docker 目标（nx docker my-project），以便在运行之间缓存打包。
在 CI 上，考虑使用原生 ARM 运行器（例如 GitHub Actions 的 ubuntu-24.04-arm）以完全避免 QEMU。

`cdk deploy` / `nx apply` 时缺少构建上下文

生成的 docker 目标将其构建上下文写入 dist/packages/<project>/docker/...（Python）或 dist/packages/<project>/bundle/...（TypeScript），生成的基础设施即代码指向该目录。如果在 synth 或 apply 时该目录不存在，您将看到诸如 ENOENT 或”directory does not exist”之类的错误。

生成器将 docker 目标声明为 build 的依赖项，因此 nx build（或生成的 nx deploy / nx apply 目标）将在 CDK 或 Terraform 运行之前生成构建上下文。如果您直接调用 cdk 或 terraform，请先运行 docker 步骤：

nx run my-project:docker