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 后端、部署工程和性能优化分别从哪里进入。