静态个人站部署笔记：构建、访问路径与回滚

先分清构建产物与运行服务

静态导出把页面生成 HTML、CSS、JavaScript 等文件。服务器要发布的是构建产物，而不是开发服务器或源码目录。检查时可按“域名解析 → 网络入口 → 虚拟主机 → 静态目录 → 页面资源”的顺序排查。

本文使用 example.invalid 作为示例域名，不对应本站线上配置。示例命令和路径必须按实际环境调整，不应覆盖已有站点。

首页与文章直达需要分别检查

目录形式的导出可以生成 articles/example/index.html，对应访问 /articles/example/。Nginx 的 try_files 可以先检查请求文件和目录，再返回 404。若框架导出的是 example.html，部署规则则要与之匹配。

不能用“所有未知路径都返回首页”掩盖文章 404。真正不存在的文章应返回 404；否则读者和搜索引擎会把错误页面当成有效内容。

server {
    listen 8080;
    server_name example.invalid;
    root /srv/example-static;
    index index.html;
    location / { try_files $uri $uri/ =404; }
}
# 教学配置：不包含 TLS 与现有站点迁移步骤

容器端口与公网入口分开理解

若容器里的静态服务器监听 80，可以在已有反向代理后将它映射到宿主机回环地址的一个端口。Docker 的端口发布地址决定了宿主机上的监听范围；需要把外部入口、TLS 和服务内部端口分别检查。

• 确认挂载的是 out 产物，且文件只读。
• 本机检查首页、文章深层路径、CSS 与图片。
• 再通过正式域名检查 HTTPS、重定向和资源加载。

docker run --rm -p 127.0.0.1:18088:80 \
  -v "$PWD/out:/usr/share/nginx/html:ro" nginx:stable-alpine

发布前保留可恢复的版本

为每次发布记录构建来源、构建时间、产物校验值和发布目录。先把产物放到独立候选目录完成检查，再按已有发布方式切换。不要在没有备份的情况下清空当前目录。

旧 HTML 可能短时间仍在浏览器缓存中，因此更新时还要考虑旧 HTML 引用的静态资源是否保留。对小型个人站，也应至少验证一次刷新后的文章页和手机访问。

用检查表代替“看起来可以”

发布完成后，从外部网络直接访问首页和一篇文章，再刷新文章页。确认站内导航、下载、备案链接、404 都正常。回滚时应恢复前一版完整产物，而不是只恢复首页 HTML。

参考资料

• Nginx：try_files 官方说明 ↗
• Docker：端口发布与映射 ↗