Docker 跨平台构建 mcporter 二进制文件

---
summary: 'Cross-platform binary build using Docker for mcporter: builds all platform binaries in an isolated container.'
read_when:
  - 'Building mcporter binaries for multiple platforms'
  - 'Need to build without installing Bun locally'
  - 'Want reproducible, isolated builds'
---

# Docker Cross-Platform Build

MCPorter provides a Docker-based build script that creates cross-platform binaries in an isolated container. This ensures consistent build environments and prevents local system pollution.

## Quick Start

```bash
# Run the Docker build script
./docker_build.sh

# Or use pnpm
pnpm build:docker
```

## Build Targets

| Platform | Architecture | Target | Output |
| --- | --- | --- | --- |
| Linux | amd64 | `bun-linux-x64` | `mcporter-linux-amd64` |
| Linux | arm64 | `bun-linux-aarch64` | `mcporter-linux-arm64` |
| macOS | amd64 | `bun-darwin-x64` | `mcporter-macos-amd64` |
| macOS | arm64 | `bun-darwin-aarch64` | `mcporter-macos-arm64` |
| Windows | amd64 | `bun-windows-x64` | `mcporter-windows-amd64.exe` |
| Windows | arm64 | `bun-windows-aarch64` | `mcporter-windows-arm64.exe` |

## Prerequisites

- Docker installed and running
- Access to Docker Hub (to pull `oven/bun:latest` image)
- Write permissions to project directory

## Output Directory

All binaries are output to the `build/` directory in the project root:

```
build/
├── mcporter-linux-amd64
├── mcporter-linux-arm64
├── mcporter-macos-amd64
├── mcporter-macos-arm64
├── mcporter-windows-amd64.exe
└── mcporter-windows-arm64.exe
```

## Docker Image

The script uses the official `oven/bun:latest` image, which includes:
- Latest Bun runtime
- Build dependencies for all target platforms
- Minimal Debian base (~200MB)

The image is pulled automatically on first run and cached for subsequent builds.

## Script Internals

The Docker container performs:

1. **Mount** the project directory as `/workspace`
2. **Install** dependencies via `bun install`
3. **Build** each target using `bun scripts/build-bun.ts`
4. **Output** binaries to `/workspace/build/` (mapped to host `build/`)

Container is cleaned up automatically (`--rm` flag) after build completes.

## Verification

After building, verify the output:

```bash
# Check output files
ls -lh build/

# Test Linux binary
./build/mcporter-linux-amd64 --version

# Verify static linking (Linux)
ldd build/mcporter-linux-amd64
# Should output: "not a dynamic executable"
```

## Local vs Docker Build

| Feature | `build.sh` (Local) | `docker_build.sh` (Docker) |
| --- | --- | --- |
| Requires Bun installed | Yes | No |
| Output directory | `dist-bun/` | `build/` |
| Build environment | Host system | Isolated container |
| Reproducibility | Depends on host | Consistent |
| Startup cost | Instant | First run: pull image |

## Customization

To customize the build:

1. **Change Docker image**: Edit `DOCKER_IMAGE` in `docker_build.sh`
2. **Modify targets**: Edit the `TARGETS` array
3. **Add flags**: Pass additional arguments to `bun scripts/build-bun.ts`

Example for single-target build:

```bash
docker run --rm \
  -v "$PWD:/workspace" \
  -w /workspace \
  oven/bun:latest \
  bash -c '
    bun install
    bun scripts/build-bun.ts \
      --target bun-linux-x64 \
      --output build/mcporter-linux-amd64
  '
```

最后修改：2026 年 03 月 02 日