05 部署(一):镜像与多阶段构建
一句话结论:多阶段构建不是为了把 Dockerfile 写得复杂,而是让运行层只拿到
.output和content/,把源码、构建工具和 root 权限留在构建阶段;这样镜像更小、启动更稳,服务器也不必替开发机干活。
它解决什么问题
第一次写 Dockerfile 时,我很容易写成「把项目复制进去,npm install,npm run build,npm start」。在本机这样能跑,但它把三件不同的事塞进了同一个容器:安装依赖、构建产物、运行服务。结果是运行镜像里同时留着源码、node_modules 的全部开发依赖、构建缓存,以及一个可能拥有 root 权限的进程。
这个站最终要跑在一台 2GB 内存的轻量服务器上。它需要做的事情很清楚:拉取一个已经构建好的镜像,启动 Node 进程,响应 Caddy 转发过来的请求。它不应该在每次发布时安装几百个 npm 包、执行 nuxt build,再和构建缓存抢内存。构建应该发生在开发机或 CI 上,服务器只负责运行。
还有一个容易被忽略的点:这个站的内容不是从数据库读的,而是从 content/ 目录读的。如果镜像里只有 .output,没有 content/,页面在本地能打开,部署后却会报找不到内容。内容必须和构建产物一起进入镜像,成为可交付物的一部分。
我怎么试的
1. 先画三个阶段
我把 Dockerfile 拆成 deps、build、runtime 三个阶段,每一阶段只回答一个问题:
| 阶段 | 里面有什么 | 产出 | 不进入运行层的东西 |
|---|---|---|---|
deps |
package.json、package-lock.json |
完整的 node_modules |
源码、构建缓存 |
build |
源码、content/、上一步的 node_modules |
.output/ |
开发依赖、源码 |
runtime |
.output/、content/ |
一个可运行的 Node 服务 | npm、源码、构建工具 |
这样分层之后,运行层不需要知道项目是用 Nuxt 还是别的框架构建的,它只需要知道入口是 .output/server/index.mjs。
2. deps:只复制清单,跳过 postinstall
依赖层只复制两个文件:
FROM node:24-alpine AS deps
WORKDIR /app/frontend
COPY frontend/package.json frontend/package-lock.json ./
RUN npm ci --ignore-scripts
这里用 npm ci 而不是 npm install。npm ci 严格按照 lockfile 安装,不会顺手更新依赖版本,构建结果更可重复。只复制清单文件,是为了让源码变化不会让这一层缓存失效;只要依赖没变,Docker 可以直接复用上一次的 node_modules。
--ignore-scripts 是为了跳过 postinstall。项目里的 postinstall 会执行 nuxt prepare,它需要源码和 nuxt.config.ts 已经就位;在 deps 阶段这些文件还没复制进来。与其在错误的阶段执行,不如先跳过,等 build 阶段再让 npm run build 自己完成必要的准备。
3. build:把 content 一起烤进镜像
构建阶段复制源码和内容,然后执行真正的构建:
FROM node:24-alpine AS build
WORKDIR /app/frontend
ENV NUXT_CONTENT_DIR=/app/content
COPY --from=deps /app/frontend/node_modules ./node_modules
COPY frontend/ ./
COPY content /app/content
RUN npm run build
COPY content /app/content 这一行很关键。前端的 runtimeConfig.contentDir 默认指向仓库根目录的 content/,容器里没有这个相对路径,所以用 NUXT_CONTENT_DIR 显式指向 /app/content。构建时,loadContent 会读这个目录,prebuild 也会先跑内容校验;frontmatter 写错、slug 重复、日期非法,都会在这里让构建失败,而不是等到线上才出现空页面。
构建完成后,真正需要带走的是 frontend/.output 和 content/;源码、node_modules 和构建缓存都留在这个阶段。
4. runtime:只留能跑的东西
运行阶段从构建阶段复制产物:
FROM node:24-alpine AS runtime
WORKDIR /app
ENV NODE_ENV=production
ENV HOST=0.0.0.0
ENV PORT=3000
ENV NUXT_CONTENT_DIR=/app/content
COPY --from=build --chown=node:node /app/frontend/.output ./.output
COPY --from=build --chown=node:node /app/content ./content
USER node
EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=3s --start-period=15s --retries=3 \
CMD wget -qO- http://127.0.0.1:3000/api/health > /dev/null || exit 1
CMD ["node", ".output/server/index.mjs"]
USER node 让进程以非 root 用户运行。Node 官方镜像自带 node 用户,--chown=node:node 保证它能读复制进来的文件。健康检查打的是 /api/health,这个接口会实际加载内容并返回条目数,不是简单返回一个固定的 ok;容器是否健康,和内容能否被读到是同一件事。
5. 在本机先验证镜像
在推送到任何仓库之前,我先在本机构建并运行:
docker build -t ednotes:local .
docker run --rm -p 3000:3000 \
-e NUXT_PUBLIC_SITE_URL=http://localhost:3000 \
ednotes:local
另一个终端检查健康接口:
curl -s http://127.0.0.1:3000/api/health
# {"status":"ok","notes":9}
notes 是当前可发布内容的数量,草稿不计入。看到这个数字,至少说明镜像里的内容目录、构建产物和运行时路径是对上的。再打开首页和一篇详情页,确认图片、RSS 和 sitemap 都能访问,才算这次镜像构建完成。
我还会进容器看一眼实际内容:
docker run --rm --entrypoint sh ednotes:local -c 'ls /app && du -sh /app/.output /app/content'
如果 /app 里出现 frontend、node_modules 或源码目录,说明某一层复制多了。运行镜像应该只有 .output、content 和 Node 运行时需要的东西;这不是洁癖,而是减少攻击面和镜像体积的第一道检查。
6. 为什么不在服务器上构建
有人会问:既然服务器已经装了 Docker,为什么不直接把源码 git clone 过去,在服务器上 docker compose build?答案不是「不能」,而是「不适合这台机器」。
构建阶段要安装全部依赖、执行 Nuxt 构建、生成客户端和服务端产物。这个过程会同时吃 CPU 和内存,峰值往往比运行时高得多。服务器只有 2GB 内存,平时还要跑 Caddy 和现有容器;构建时一旦内存不足,Linux 的 OOM killer 可能先杀掉正在提供服务的进程,而不是构建进程。把构建放在开发机或 CI 上,服务器只做 pull 和 up,故障面小得多。
坑和限制
1. 基础镜像也可能拉不下来。 在国内网络里,直接从 Docker Hub 拉 node:24-alpine 经常超时。项目后来把默认 NODE_IMAGE 指向 ACR 里的 Node 镜像,本地和 GitHub Actions 再用 --build-arg 覆盖。Dockerfile 本身不应该假设某个 registry 一定可达。
2. 内容被烤进镜像,改一篇文章也要重建。 这是当前架构的取舍:内容随镜像发布,回滚镜像就能回滚内容,但写作后不能只改服务器上的文件。修改 content/ 后必须重新构建镜像,否则线上看到的还是旧内容。
3. --ignore-scripts 不是无代价的。 它跳过了所有依赖的安装脚本,包括一些需要编译原生模块的包。这个项目目前没有这类依赖,所以没问题;如果以后引入,需要在 build 阶段显式补上。
4. Apple Silicon 上构建的镜像默认不是 linux/amd64。 服务器是 x86_64,本地如果是 M 系列芯片,直接 docker build 出来的镜像在服务器上跑不起来。发布时必须用 buildx --platform linux/amd64,这一点在下一篇会展开。
5. build context 会把不必要的东西送进 Docker。 在仓库根目录构建时,. 会把 .git、frontend/node_modules、.output 都作为上下文传给 Docker。项目用 .dockerignore 排除了这些目录,否则构建会变慢,镜像层也可能混入旧产物。
6. 不要在这台 2GB 服务器上构建。 依赖安装和 Nuxt 构建都会吃内存,构建时再跑 Caddy 和现有容器,很容易触发 OOM。服务器的角色是 pull 和 up,不是 build。
适合谁
这篇适合已经会用 docker build、docker run,但还没认真写过生产 Dockerfile 的前端。它不涉及 Kubernetes、多节点调度或镜像签名;目标只是让一个 Nuxt 应用以可重复的方式跑起来,并且知道哪些东西应该留在构建阶段。