Dockerfile 实战：Go 后端与 Next.js 前端如何打镜像

动手前先知道

这篇文章对应的真实任务是：围绕 Go 后端和 Next.js 前端讲解多阶段构建、.dockerignore、配置注入和构建失败排查。

第一次阅读先弄清“为什么需要这一步、它改变了哪个运行对象、失败时去哪里检查”，再执行命令。命令可以查，运行模型和排障路径才是长期能力。

Dockerfile 是项目容器化的核心。写得好，镜像小、构建快、上线稳定；写得随便，镜像会变大，构建会变慢，还容易把密钥、缓存、源码垃圾一起打进去。

Dockerfile 的基本原则

写 Dockerfile 时优先考虑这几件事：

构建阶段和运行阶段分离。
先复制依赖文件，再复制业务代码，提高缓存命中率。
最终镜像只保留运行必需内容。
不把 .env.local、密钥、临时文件打进镜像。
容器启动命令要明确。

Go 后端 Dockerfile 思路

Go 项目适合多阶段构建：

FROM golang:1.24-alpine AS builder
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -o /out/server ./cmd/server

FROM alpine:3.21
WORKDIR /app
RUN apk add --no-cache ca-certificates tzdata
COPY --from=builder /out/server /app/server
EXPOSE 8080
CMD ["/app/server"]

它的好处是：

编译工具链不会进入最终镜像。
最终镜像更小。
运行环境更干净。

如果后端需要 CGO、图片处理、数据库驱动依赖系统库，就不能简单关闭 CGO，需要根据实际依赖调整。

Next.js 前端 Dockerfile 思路

Next.js 项目可以使用 standalone 输出，让运行镜像更轻。

思路是：

安装依赖
  ↓
构建 Next.js
  ↓
复制 standalone、static、public
  ↓
启动 server.js

重点不是背某个模板，而是知道最终运行需要哪些文件。

.dockerignore 很重要

.dockerignore 用来避免无关文件进入构建上下文。

建议排除：

node_modules
.next
.git
.env
.env.local
coverage
dist
.cache
*.log

如果不写 .dockerignore，构建会慢，还可能把敏感配置打进镜像。

镜像里的配置怎么处理

生产配置不应该写死进镜像。镜像应该是“同一份镜像，不同环境注入不同配置”。

例如：

services:
  api:
    image: xiaoai-blog-api:2026-09-03
    env_file:
      - .env.production

这样镜像是可复用的，配置由部署环境决定。

构建失败怎么排查

常见问题：

依赖下载失败：检查网络、代理、镜像源。
COPY 路径不对：检查 Dockerfile 的构建上下文。
构建产物不存在：检查 build 命令是否真的输出目标文件。
容器启动失败：检查 CMD、环境变量、端口。

构建时可以先不急着 Compose，单独构建镜像：

docker build -t xiaoai-blog-api:test ./backend

再单独启动验证：

docker run --rm -p 8080:8080 xiaoai-blog-api:test

先让单个镜像正确，再进入 Compose 编排，会少很多混乱。