下面是我这个博客站点实际的部署方式。

整体思路​

两阶段构建：

1. builder 阶段：用 node:22-alpine 跑 npm ci && npm run build，产出 build/ 静态文件。
2. serve 阶段：把 build/ 拷进 nginx:alpine，用 nginx 托管。

最终镜像里没有 Node、没有源码、没有 node_modules，只有 nginx + 静态文件，体积大概 50MB 出头。

Dockerfile​

# ==================== Stage 1: Build ====================
FROM node:22-alpine AS builder
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build
# ==================== Stage 2: Serve ====================
FROM nginx:alpine
RUN rm /etc/nginx/conf.d/default.conf
COPY nginx.conf /etc/nginx/conf.d/default.conf
COPY --from=builder /app/build /usr/share/nginx/html
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

几个细节：

• 先 COPY package.json package-lock.json 再 npm ci，最后才 COPY . .。这样只要依赖没变，npm ci 那一层就命中缓存，改文章重新构建只要几秒。
• 用 npm ci 而不是 npm install，保证依赖按 lockfile 精确安装，CI 里可复现。
• package-lock.json 必须提交进仓库，否则 npm ci 直接报错。

nginx 配置要点​

Docusaurus 是 SSG（静态站点生成），不是 SPA。这意味着每个路由在 build/ 里都有对应的 index.html，不需要 SPA 那种「所有路径回退到 index.html」的逻辑。

server {
    listen 80;
    server_name _;
    root /usr/share/nginx/html;
    index index.html;
    absolute_redirect off;

    gzip on;
    gzip_vary on;
    gzip_proxied any;
    gzip_comp_level 6;
    gzip_types text/plain text/css text/xml application/json
               application/javascript application/xml+rss
               application/atom+xml image/svg+xml;

    location / {
        try_files $uri $uri/ =404;
    }

    location ~* \.(?:js|css|woff2?|ttf|eot|png|jpg|jpeg|gif|ico|svg|webp)$ {
        expires 30d;
        add_header Cache-Control "public, immutable";
        access_log off;
    }

    location ~* \.html$ {
        add_header Cache-Control "no-cache, no-store, must-revalidate";
    }

    error_page 404 /404.html;
}

关键点：

• try_files $uri $uri/ =404：先找精确文件，再找目录（落到 index.html），都没有就 404。千万别写成 try_files $uri $uri/ /index.html，那是 SPA 回退，会让 Docusaurus 的 404 页失效、所有错误路径都返回首页。
• HTML 不缓存：文章更新后能立刻生效；而带 hash 的 JS/CSS 设置长期不可变缓存，再访问直接走浏览器缓存。
• absolute_redirect off：nginx 目录重定向默认会用绝对地址，开了这个更可控。
• gzip：把 application/atom+xml 也加上，RSS feed 才会被压缩。

踩过的坑​

1. npm ci 报缺 package-lock.json​

最初我图省事没提交 lockfile，CI 里 npm ci 直接挂了。npm ci 是严格模式，没有 lockfile 不干活。lockfile 必须进版本控制。

2. 容器里访问 404 但本地 docusaurus serve 正常​

本地 npm run serve 用的是 Docusaurus 内置服务，带 SPA 回退；而 nginx 是纯静态。如果构建时有 broken link，本地可能看不出来，nginx 下就是 404。所以 docusaurus.config.ts 里我把 onBrokenLinks 设成 'throw'，构建阶段就直接挂掉，不留到部署。

3. 构建产物路径​

Docusaurus 默认输出到 build/，baseUrl 决定了产物里的子路径。我这个站点 baseUrl: '/'，所以 build/ 直接就是 web root，COPY --from=builder /app/build /usr/share/nginx/html 刚好对上。如果 baseUrl 不是 /，nginx 的 root 和 location 都要相应调整。

4. 前置反代偶发 504​

容器跑起来后，外面套一层 nginx-ui 反向代理做 TLS。一开始偶发 504，排查下来是容器 mem_limit 太紧、峰值时 nginx worker 被挤掉，反代侧表现为超时。把内存上限放宽、给静态资源开长缓存之后就好了。反代那侧 proxy_read_timeout 设 30s，足够了。详见我另一篇 排查 nginx 反向代理 502/504 错误。

构建与运行​

docker compose up -d --build

docker-compose.yml 里把容器 80 映射到宿主机 8080，再由 192.168.1.3 上的 nginx-ui 反代到 https://www.anderslane.cn。整条链路：浏览器 → nginx-ui (TLS) → 容器 nginx (静态文件)。

小结​

多阶段构建 + nginx 托管静态文件，是 SSG 站点最干净的部署方式之一：构建环境和运行环境彻底分离，镜像小、启动快、无状态。唯一要记住的是 SSG 不等于 SPA，别用 SPA 的回退逻辑。

环境​

• 浏览器 → 192.168.1.3 上的 nginx-ui（反代，终止 TLS）
• nginx-ui → 192.168.1.5:8080 上的容器（nginx 托管静态文件）

偶发，不是必现，大概十次里一两次。

现象​

• 大部分请求正常 200。
• 偶发 502 Bad Gateway，或 504 Gateway Timeout。
• 刷新一下往往就好了。

排查思路​

502/504 的本质是「反代拿不到上游的有效响应」。要么上游没响应（504 超时），要么上游拒绝了连接 / 连接被重置（502）。所以排查分两条线：

1. 上游本身是不是活的——容器 nginx 在不在、监听对不对。
2. 反代到上游的网络通不通——连接能不能建立、建立后能不能在超时内完成。

第一步：确认上游存活​

# 容器状态
docker ps | grep www-anderslane

# 容器内 nginx 监听
docker exec www-anderslane wget -qO- http://localhost:80/ | head -5

# 从反代机直接打上游
curl -v -H 'Host: www.anderslane.cn' http://192.168.1.5:8080/

结果：容器在，监听正常，从反代机 curl 上游也 200。说明上游是活的，问题出在「偶发」上。

第二步：看反代错误日志​

# nginx-ui 容器的错误日志
docker logs <nginx-ui-container> 2>&1 | grep -E 'upstream|502|504'

抓到关键几行：

upstream timed out (110: Connection timed out) while reading response header from upstream
upstream prematurely closed connection while reading response header from upstream

两类错误：

• Connection timed out：TCP 连上了，但上游迟迟不回响应头 → 504。
• upstream prematurely closed connection：连接建立后被上游主动关了 → 502。

第三步：上游资源排查​

容器是静态文件服务，怎么会超时？看容器资源：

docker stats --no-stream www-anderslane

发现偶发时段 CPU 飙到接近 100%，内存也接近上限（docker-compose.yml 里限了 256m）。再看进程：

docker exec www-anderslane ps aux

nginx worker 之外，多了一堆 wget --spider 进程——那是 healthcheck。

根因​

docker-compose.yml 的健康检查：

healthcheck:
  test: ["CMD", "wget", "--spider", "-q", "http://localhost:80/"]
  interval: 30s
  timeout: 5s
  retries: 3

wget --spider 在 alpine 上实际会发起请求并解析响应，30s 一次本不算频繁。但 mem_limit: 256m 偏紧，nginx 在高并发或被健康检查挤占时，worker 偶发 OOM 被杀、连接被重置 → 反代侧表现就是 502/504。

两条因素叠加：

1. 内存上限太紧，峰值时 worker 被杀。
2. 健康检查和正常请求抢资源，放大了峰值。

处理​

1. 放宽内存上限到 512m，给 nginx worker 留余量。
2. 健康检查换成更轻的探测，直接打一个静态小文件，少解析。
3. 反代侧 proxy_read_timeout 设 30s（本来就是），proxy_connect_timeout 设 5s 快速失败。
4. 给静态资源开 expires 长缓存，减少回源压力。

改完观察两天，502/504 消失。

复盘​

几条经验：

• 偶发 502/504 先看上游资源，别一上来就调反代超时。超时只是症状，根因往往是上游扛不住。
• 容器资源限制要留余量，256m 对 alpine + nginx 平时够用，但峰值（OOM 边缘）会偶发杀进程，很难复现。
• 健康检查本身也是负载，在资源紧张的容器里别用重检查。
• 日志是最快的线索：upstream timed out vs prematurely closed 区分了超时和重置，直接指向不同方向。

排查这类问题的顺序我习惯是：上游存活 → 上游资源 → 网络/超时 → 反代配置。前两步排掉，剩下的基本就是配置调优了。

这次重新搭博客，我认真对比了当下三个主流的静态站点生成器（SSG）：Hugo、Astro、Docusaurus。结论是选了 Docusaurus。不是因为它最好，而是因为它最契合我「写技术博客」这个具体场景。

三个候选​

Hugo​

Go 写的，主打一个快。构建几千篇文章只要几百毫秒，单二进制部署，没有依赖地狱。

• 优点：构建飞快，单文件，主题生态成熟。
• 缺点：模板是 Go template，写复杂逻辑很拧巴；默认主题多偏「文档站」或老派博客；要做出自己想要的样子，改主题的成本不低。

Astro​

新生代，主打 Islands Architecture，默认尽量少发 JS 到前端。可以混用 React / Vue / Svelte。

• 优点：现代、灵活，性能好，组件化，能做出很精致的页面。
• 缺点：对「纯文字博客」来说有点重；要配置的东西多；生态相对新，内容插件（比如 RSS、归档）要自己搭。

Docusaurus​

React + MDX，Meta 出品。原本定位是文档站，但 blog 插件很完整。

• 优点：MDX 写作、代码块高亮开箱即用、RSS / 归档 / TOC 都现成、React 生态可复用、TypeScript 支持好。
• 缺点：构建产物带一定量 JS（比 Hugo 重）；定位偏文档，做博客要稍微「裁掉」一些默认元素。

我的取舍​

我的需求很具体：

1. 以文章时间流为主，不要分类树、不要复杂的文档结构。
2. 写技术文章，代码块、TOC、MDX 组件是高频需求。
3. 能精细控制主题，想要一个克制的极简风，而不是套现成主题。
4. TypeScript + React，跟我日常技术栈一致，改起来顺手。

逐条对：

• 需求 1：三个都能做。Hugo 默认就是博客起家；Astro 和 Docusaurus 都能裁成纯时间流。
• 需求 2：Docusaurus 完胜。MDX + Prism 代码高亮 + 自动 TOC + 阅读体验，开箱即用。Hugo 要自己配高亮和 shortcodes，Astro 要自己接插件。
• 需求 3：三个都能改主题，但 Docusaurus 的 Infima 体系 + CSS 变量改起来很线性，覆盖一个 custom.css 就能大改。Hugo 主题是一大坨模板，魔改成本高。Astro 灵活但要自己搭整套布局。
• 需求 4：只有 Docusaurus 是 React / TS 原生。Hugo 是 Go template，Astro 虽支持 React 但本体是 .astro。

所以选 Docusaurus。代价是构建产物比 Hugo 重一点、带些 JS，但对我来说这点体积完全可接受——技术博客又不追求极致 LCP，可读性才是第一位。

实际怎么裁​

Docusaurus 默认是个「文档站 + 博客」的形态，要做纯博客得裁掉一些东西：

• 关掉 docs 插件：preset-classic 里 docs: false，只留 blog。
• 博客当首页：blog 插件设 routeBasePath: '/'，主页直接是文章列表。
• 去掉标签：我个人不喜欢标签云，文章不写 tags，保持纯时间流。
• 保留归档和 RSS：这两个是博客的基本盘，Docusaurus blog 插件默认就给。
• 极简主题：覆盖 custom.css，黑白为主 + 单一强调色，正文限宽 680px，行高 1.7，参考 overreacted.io 那种阅读体验。

裁完之后，它就是一个干净的博客，没有文档站的 sidebar、没有 hero banner、没有多余卡片。

会再换吗​

大概率不会。SSG 这东西，迁移成本主要在内容和主题。内容是 Markdown / MDX，可移植；主题是自己写的 CSS，也清楚。真要换，文章搬走不难。但 Docusaurus 目前满足我所有需求，没有换的理由。

选工具的真相是：没有最好的，只有最契合当前场景的。对我这个「会 React / TS、想精细控制样式、写技术文章为主」的人来说，Docusaurus 就是当前的最优解。