跳到主要内容
Ed. notes

08 构建与交付:从本地到上线

长文 · 2026-11-12 · 合集第 9 / 10 篇

  • 构建
  • Docker
  • CI
  • Caddy
  • 构建日志
第 9 / 10 篇 · 查看全部章节 → 当前:08 构建与交付:从本地到上线

结论

从本地到上线可以压缩成一条链:

content:validate
  → nuxt build
  → .output/
  → Docker 多阶段镜像
  → Caddy 反向代理
  → CI 质量门与发布

每一段回答一个问题:内容是否合法、前端能否构建、运行时是否最小、入口是否稳定、改动是否经过检查。博客部分在前四段就完整了;Caddy、CI 和发布策略是把它送上线所需的工程外壳。

问题与设计

内容错误要在构建前失败

package.json 里 prebuild 指向内容校验脚本:

{
  "scripts": {
    "prebuild": "node scripts/validate-content.mjs",
    "build": "nuxt build"
  }
}

执行 npm run build 时,npm 会先跑 prebuild。frontmatter 写错、日期不存在、slug 冲突,都会在 Nuxt 开始构建前失败。镜像构建也调用同一个命令,所以不会出现「本地校验过、镜像里内容坏了」的分叉。

构建依赖和运行依赖分开

Dockerfile 分三个阶段:

  • deps:只复制 package.json 和 lockfile,安装依赖,利用层缓存;
  • build:复制源码和 content/,执行 npm run build;
  • runtime:只复制 .output/ 和 content/,不包含源码、npm 缓存和 devDependencies。

运行镜像用非 root 用户,暴露 3000,健康检查走 /api/health。

内容进镜像,而不是挂载

这个站的内容和代码一起发布:镜像里同时有 .output/ 和 content/。这样部署只需要一个镜像,不需要额外同步 Markdown;代价是改一篇文章也要重新构建镜像。

对当前规模这是有意的取舍:内容变更频率低,镜像可回滚,部署链路简单。以后如果内容更新频率变高,再把 content/ 拆成挂载卷或独立内容服务。

Caddy 负责入口

Caddy 做三件事:自动 HTTPS、压缩、反向代理到 app:3000。它还统一加 X-Content-Type-Options: nosniff 和 Referrer-Policy。应用本身不处理 TLS,也不暴露公网端口。

CI 不是自动发布

CI 的职责是证明改动没有破坏已知契约:lint、样式、格式、类型、单元测试、构建、端到端和 axe。发布仍然是一个需要明确版本的动作。这个边界在 构建实践 的 CI 三篇里有更完整的讨论。

关键代码

本地构建

cd frontend
npm run content:validate
npm run build
npm run preview

build 会再次触发内容校验;preview 只用于检查生产产物,不代表生产环境。

三阶段 Dockerfile

ARG NODE_IMAGE=node:24-alpine

FROM ${NODE_IMAGE} AS deps
WORKDIR /app/frontend
COPY frontend/package.json frontend/package-lock.json ./
RUN npm ci --ignore-scripts

FROM ${NODE_IMAGE} 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

FROM ${NODE_IMAGE} 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"]

真实仓库把 NODE_IMAGE 默认值指向团队镜像仓库,避免构建机访问 Docker Hub 超时;公开复现时可以用 --build-arg NODE_IMAGE=node:24-alpine 覆盖。文章里不写具体仓库地址。

Caddy 配置

{$SITE_DOMAIN:localhost} {
	encode zstd gzip

	header {
		X-Content-Type-Options nosniff
		Referrer-Policy strict-origin-when-cross-origin
	}

	reverse_proxy app:3000
}

SITE_DOMAIN 由环境变量提供。域名解析正确时,Caddy 会自动申请和续期证书。

运行镜像

docker build -t ednotes:local .
docker run --rm -p 3000:3000 \
  -e NUXT_PUBLIC_SITE_URL=http://localhost:3000 \
  ednotes:local

然后检查:

curl http://localhost:3000/api/health
curl -I http://localhost:3000/

CI 检查顺序

lint → lint:styles → format:check → typecheck → test → build
  → Playwright 端到端 → axe 可访问性 → 镜像校验

前面的检查几秒到几十秒就能失败,不应该排在浏览器测试后面。CI 全绿只说明契约没被破坏,不等于已经发布。

验证

本地最小验收:

cd frontend
npm run content:validate
npm run build
npm run preview

打开预览地址,确认首页、目录、详情、/rss.xml、/sitemap.xml 和 /api/health 正常。

镜像验收需要 Docker:

docker build -t ednotes:local .
docker run --rm -p 3000:3000 \
  -e NUXT_PUBLIC_SITE_URL=http://localhost:3000 \
  ednotes:local

另开终端确认 /api/health 返回 status: ok。生产环境还要把 NUXT_PUBLIC_SITE_URL 换成真实域名,否则 RSS 和 sitemap 会写 localhost。

边界

  • 本文不展开镜像仓库、VPC 拉取、commit tag 回滚;这些在 构建实践 的部署两篇里。
  • npm run preview 不是生产环境,生产还涉及域名、TLS、进程管理和反向代理。
  • 内容打进镜像,改文章需要重新构建;当前没有挂载卷或增量内容发布。
  • CI 全绿不等于线上健康;发布后仍要检查 /api/health 和关键页面。
  • AI 助手的 /api/chat 没有鉴权、配额和限流,生产默认关闭;不要因为博客上线就顺手公开它。
  • 性能优化不是构建链的自动产物;Lighthouse、字体和图片的账在 如何优化。

下一篇把博客之后的阅读路线列清楚:AI 前端、AI 后端、部署工程和性能优化分别从哪里进入。