# 构建失败：构建器实例不支持平台'linux/arm64/v8'

- **ID:** `cicd/docker-buildx-platform-not-supported`
- **领域:** cicd
- **类别:** build_error
- **错误码:** `PLATFORM_NOT_SUPPORTED`
- **验证级别:** ai_generated
- **修复率:** 83%

## 根因

Docker Buildx构建器没有启用请求的平台（例如ARM64），或未安装用于跨平台构建的QEMU仿真。

## 版本兼容性

| 版本 | 状态 | 引入 | 弃用 |
|------|------|------|------|
| Docker 24.0 | active | — | — |
| Buildx 0.12 | active | — | — |
| QEMU 7.2 | active | — | — |
| Linux x86_64 host | active | — | — |

## 解决方案

1. ```
   Install QEMU binfmt support: `docker run --privileged --rm tonistiigi/binfmt --install all`, then create builder: `docker buildx create --name multiarch --driver docker-container --bootstrap`
   ```
2. ```
   Use existing multiarch builder: `docker buildx use multiarch && docker buildx inspect --bootstrap` to verify platforms
   ```
3. ```
   In CI, add step to setup QEMU: `uses: docker/setup-qemu-action@v3` and `uses: docker/setup-buildx-action@v3` before build
   ```

## 无效尝试

- **** — Default driver doesn't support multi-platform builds at all; fails with different error. (75% 失败率)
- **** — Avoids the error but defeats the purpose of multi-platform builds; doesn't fix builder configuration. (40% 失败率)
- **** — Default builder may not include QEMU or ARM emulation; need explicit --driver-opt. (55% 失败率)