Docker构建Swift时出现x86_64架构未定义符号错误的原因

问题拆解 #

你碰到的问题本质是Apple Silicon（ARM64）环境与Heroku的x86_64运行环境不兼容，加上Docker构建时的命令错误、本地依赖库架构不匹配导致的连锁问题：

1. Heroku容器注册表拒绝ARM64镜像，要求构建x86_64版本
2. Docker容器内swift build命令参数解析解析失败
3. 本地交叉编译时依赖ARM64版本的cmark库，导致x86_64链接失败

分步解决 #

1. 修正Dockerfile的构建命令与基础镜像 #

Unexpected argument '/usr/bin/swift-build'错误是因为Dockerfile中swift build的换行转义或基础镜像架构不对：

• 改用x86_64专属的Swift基础镜像，确保容器内环境是纯x86_64
• 检查构建命令的换行转义，避免多余空格或无效字符

修改后的Dockerfile核心片段：

# 明确使用x86_64架构的Swift镜像，版本根据项目需求调整
FROM swift:5.9-amd64 as build-stage

WORKDIR /app

# 复制项目源码到容器内
COPY Package.swift Package.resolved ./
COPY Sources ./Sources
COPY Tests ./Tests

# 执行构建，确保命令无多余转义
RUN swift build -j 1 --configuration release --product Server -Xswiftc -g \
    && swift build -j 1 --configuration release --product Runner -Xswiftc -g

2. 用Docker完成全容器内构建，不依赖本地环境 #

不要在本地主机执行swift build，所有构建步骤放在Docker容器内完成，彻底避免本地ARM64库（比如brew安装的cmark）干扰：

# 构建x86_64架构镜像，命名为heroku-web
docker build --platform linux/amd64 -t heroku-web .

3. 重新推送镜像到Heroku #

构建成功后，按流程推送并发布：

# 登录Heroku容器注册表
heroku container:login

# 推送镜像到你的Heroku应用，替换<your-app-name>为实际应用名
heroku container:push web --app <your-app-name>

# 发布应用
heroku container:release web --app <your-app-name>

4. 启用Docker的Rosetta模拟（可选） #

如果Docker仍无法正确模拟x86_64环境，开启Rosetta支持：

• 打开Docker Desktop -> 设置 -> Features in development -> 勾选「Use Rosetta for x86/amd64 emulation on Apple Silicon」
• 重启Docker后重新构建

重要提醒 #

• 容器构建必须完全隔离：所有依赖（包括cmark）通过Swift Package Manager或容器内的包管理器安装，绝对不要依赖本地主机的库
• 清理缓存：如果之前构建过ARM64镜像，先执行docker system prune -af清理旧镜像和缓存，避免残留干扰
• 验证架构：构建完成后可以用docker inspect heroku-web | grep Architecture确认镜像架构是amd64

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