跳到正文
零到全栈 · 卷 3 · 工程化与版本控制

把工程发布到公网

本合集目录
本章目录

单册说明:本文件是卷 3 的第 7 章,可独立阅读。前置:第 6 章(dist/ 产物)、卷 1 第 6 章(Nginx 默认站)。本章把 dist/ 放进带时间戳的版本目录,用软链切换,做到一条命令上线、一条命令回滚。

项 内容
所属卷 卷 3 · 工程化与版本控制(第 7 / 7 章)
前置章节 3.6 Vite 开发与构建
本章产出 一台服务器上的 releases/ + current 结构 · 一份 Nginx 配置 · 一个 deploy.sh · 一次成功的回滚
对应代码 dudao/deploy.sh、/etc/nginx/sites-available/dudao(服务器侧)
配图 无(后续统一制图)
读完的判定 能在 30 秒内把线上切回上一版,并用 curl -I 证明切换成功

3.7.1 一句话结论:发布是换软链,不是覆盖文件

把新版本解压到一个新目录,再把 current 这个软链指过去——切换是原子的:要么全指向旧目录,要么全指向新目录,不会出现"HTML 是新版、CSS 还是旧版"的中间状态。回滚就是把软链指回去,一秒钟,不需要重新构建。

真实失败场景:你 scp -r dist/* /var/www/dudao/,覆盖到一半网络断了。现在服务器上是半新半旧的文件:index.html 引用了 index-新哈希.js,而那个文件没传上去。用户打开页面白屏,Console 报 404。你手上没有上一版的完整副本,只能重新构建再传一次——这就是"覆盖式发布"的代价:它没有中间态,也没有退路。

3.7.2 原理:目录、Nginx、缓存与报错

① 产物怎么上服务器

方式 命令形状 优点 缺点 适合
本地构建 + rsync rsync -az --delete dist/ host:/path/ 服务器不用装 Node,快,可增量 本机要有完整环境 推荐,本卷用这个
本地构建 + scp scp -r dist/* host:/path/ 简单 不增量、不删旧文件、断点要重来 应急
服务器 git pull + 构建 ssh host 'cd app && git pull && npm ci && npm run build' 服务器上有源码,可追溯 服务器要装 Node,构建吃内存,1 核机器容易 OOM 小项目、想在一处构建
CI 构建 + 上传 平台跑完再推 环境统一 配置成本高 团队协作、卷 8 之后

rsync 的 --delete 很重要:它让目标目录和 dist/ 完全一致,包括删掉上一版残留的旧哈希文件。没有它,assets/ 会越积越多。

② 目录结构:给每次发布留一个位置

/var/www/dudao/
├── releases/
│   ├── 20261116-2041/
│   │   ├── index.html
│   │   └── assets/
│   └── 20261117-1015/
│       ├── index.html
│       └── assets/
└── current -> /var/www/dudao/releases/20261117-1015
部分 作用
releases/<时间戳>/ 每次发布一个独立目录,互不覆盖
current 软链,Nginx 只认它,切换就是改它
保留最近 5 个 回滚有退路,磁盘也不会无限涨

为什么用时间戳而不是 v1、v2?因为时间戳天然有序、不会重名、能一眼看出"这是几点发的"。ls -1 出来的顺序就是发布顺序。

磁盘占用也要算:纯静态站一次发布通常不到 1 MB,留五个版本可以忽略;但项目一旦带上图片和字体,单版可能几十 MB,就得按数量或天数清理。保留策略要写进发布脚本,而不是等磁盘满了再手工删。

③ Nginx:root 与 try_files 各管什么

server {
    listen 80;
    server_name dudao.example.com;

    root /var/www/dudao/current;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location /assets/ {
        try_files $uri =404;
        expires 1y;
        add_header Cache-Control "public, immutable";
        access_log off;
    }

    location = /index.html {
        add_header Cache-Control "no-cache";
    }
}

还没有域名也没关系:把 server_name 写成服务器公网 IP,或者先改默认站的 root。域名与解析是卷 7 的事,本章能用 IP 打开就算通过。

root 是"文件系统里从哪找",try_files 是"按什么顺序试":

try_files 的参数 含义
$uri 把请求路径当文件找,如 /assets/index-C8kQ2m1p.js
$uri/ 当目录找,再找目录下的 index.html
/index.html 前两个都不存在时,内部转发到入口文件(SPA 回退)

SPA 回退是给前端路由用的:用户直接访问 /note/123,服务器上没有这个文件,就返回 index.html 让前端路由接管。

但它有个副作用,必须知道:一个不存在的 JS 也会命中回退,返回 200 + text/html,于是浏览器报第 6 章那段 MIME 错误。所以 location /assets/ 里单独写了 try_files $uri =404——资源目录不该有回退,找不到就是 404,这样报错才准确。

缓存策略是两条相反的规则:

文件 缓存 为什么
/assets/*-<哈希>.js、.css 一年 + immutable 内容变则文件名变,旧文件永不复用,可以放心长缓存
/index.html no-cache 它是"版本入口",必须每次回源确认,否则用户永远拿不到新哈希

no-cache 不是"不缓存",是"可以存,但每次用之前必须问服务器"。真正的"不许存"是 no-store。

④ 403 / 404 / 500 怎么分

静态站没有后端,所以不会出现 502;这三个码的含义非常固定:

状态码 最可能的原因 去哪确认
403 Forbidden 目录里没有 index.html 且未开目录列表;文件权限不允许 Nginx 读;SELinux/AppArmor 拦截 error.log 里的 (13: Permission denied)
404 Not Found 资源路径对不上:root 指错层级、少传了 dist 这一层、文件名大小写不符 error.log 里的 (2: No such file or directory),以及它尝试的完整路径
500 Internal Server Error try_files 回退到一个不存在的 index.html,形成内部循环;配置语法错误 nginx -t;error.log 里的 rewrite or internal redirection cycle

一条通用判断:403 是"找到了但不让看",404 是"根本没找到",500 是"配置或服务自己出问题了"。 三个码对应三种完全不同的修法,先分清再动手。

同一个 root 错误,可能同时表现为两种:请求页面(走 location /,有 SPA 回退)变成 500 循环,请求 JS(走 location /assets/,没有回退)变成 404。所以别只看首页状态码,要点开 Network 里具体那一条。

⑤ 为什么这一章只开 80 端口

本章的配置里只有 listen 80,没有 HTTPS。这不是遗漏,是分工:证书申请、自动续期、强制跳转属于卷 7。但有一条现在就要知道——页面一旦上了 HTTPS,它引用的所有资源也必须是 HTTPS,否则浏览器会在 Console 里报 Mixed Content(混合内容),并直接拦掉那个请求。提示的措辞各版本略有差异,核心信息固定:页面是 HTTPS,请求的资源是 HTTP,请求已被阻断,内容必须走 HTTPS。

所以从今天起,代码里不要写死 http:// 的绝对地址。站内资源一律用 /assets/... 这种相对站点根的路径,接口地址走环境变量——换域名、上 HTTPS 时只改配置,不改代码。

3.7.3 动手:发布、验证、回滚

第 0 步:发布前确认三件事

确认 怎么看 不确认的后果
源码与仓库一致 git status 干净 线上跑的代码在历史里找不到,出问题无法定位到某次提交
dist/ 是刚构建的 ls -l dist 的时间戳是刚才 发上去的是昨天的产物,"改了没生效"查半天
产物里没有敏感串 grep -rn -e password -e token dist 密钥随静态文件公开,等于直接写在首页上

第三项不是形式主义:Vite 会把你 import 的任何字符串打进产物,包括你调试时顺手写下的测试密钥。

第 1 步:本地构建

npm run build
ls dist

形如:

assets  favicon.svg  index.html

每次发布都必须重新 build,不要复用昨天的 dist/——源码可能已经变了,产物是快照不是活文件。

第 2 步:在服务器上建目录

ssh [email protected]
sudo mkdir -p /var/www/dudao/releases
sudo chown -R "$USER":www-data /var/www/dudao

chown 让当前用户能写、www-data 组能读,避免后面用 sudo rsync 把文件搞成 root 独占(那是 403 的头号成因)。

第 3 步:推送产物

回到本地,用带时间戳的目录名:

STAMP=$(date +%Y%m%d-%H%M)
rsync -az --delete dist/ [email protected]:/var/www/dudao/releases/$STAMP/

形如:

sending incremental file list
./
assets/
assets/index-C8kQ2m1p.js
assets/index-DiwrgTda.css
index.html

sent 6,412 bytes  received 92 bytes  2,168.00 bytes/sec
total size is 18,930  speedup is 2.91

注意源路径写的是 dist/(带斜杠),不是 dist。带斜杠表示"复制目录里的内容",不带表示"复制目录本身",一字之差会多出一层 dist/dist。

Windows 的 Git Bash 默认不带 rsync。两个选择:用 scp -r dist/* [email protected]:/var/www/dudao/releases/$STAMP/ 先跑通流程(缺点是不增量、不删旧文件),或者装 WSL 在 Linux 环境里用 rsync。命令不同,思路一样:先传到新目录,再切链。

第 4 步:确认文件权限

ssh [email protected] 'ls -l /var/www/dudao/releases/'

形如:

drwxr-xr-x 3 dudao www-data 4096 Nov 17 10:15 20261117-1015

目录要有 x 位(能进入),文件要可读。如果看到 -rw------- root root,Nginx 就会 403——这是下一节坑 2 的现场。

第 5 步:切软链

ssh [email protected] 'ln -sfn /var/www/dudao/releases/20261117-1015 /var/www/dudao/current'

-s 建软链,-n 表示"目标是软链时替换它而不是钻进去建链"。-n 不能省:省了会把链接建到旧目录内部,变成 current/releases/... 这种怪东西。

验证指向:

ssh [email protected] 'ls -l /var/www/dudao/current'

形如:

lrwxrwxrwx 1 dudao www-data 42 Nov 17 10:16 current -> /var/www/dudao/releases/20261117-1015

第 6 步:配置 Nginx

在服务器上新建 /etc/nginx/sites-available/dudao,内容用 3.7.2 那段,把 server_name 换成你的域名或公网 IP。启用:

sudo ln -s /etc/nginx/sites-available/dudao /etc/nginx/sites-enabled/dudao
sudo nginx -t

形如:

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

nginx -t 必须先过再 reload。 配置有错时 reload 会失败但旧进程继续跑,你以为生效了,其实还是旧配置——这是最容易浪费半小时的地方。

sudo systemctl reload nginx

第 7 步:验证

curl -I http://203.0.113.10/

形如:

HTTP/1.1 200 OK
Server: nginx/1.24.0
Content-Type: text/html
Cache-Control: no-cache

再验证一个静态资源,重点看缓存头:

curl -I http://203.0.113.10/assets/index-C8kQ2m1p.js

形如:

HTTP/1.1 200 OK
Content-Type: application/javascript
Cache-Control: public, immutable
Expires: Tue, 16 Nov 2027 10:16:00 GMT

两条都对,说明"入口不缓存、资源长缓存"的策略生效了。

第 8 步:演练回滚

先发一版新的(随便改个文案,重新 build、推一个新时间戳目录、切链),然后回滚:

ssh [email protected] 'ls -1 /var/www/dudao/releases'

形如:

20261117-1015
20261117-1042
ssh [email protected] 'ln -sfn /var/www/dudao/releases/20261117-1015 /var/www/dudao/current'
curl -I http://203.0.113.10/

页面回到上一版。整个过程没有构建、没有传文件、没有重启 Nginx——因为旧目录一直完整地在那儿。

第 9 步:写成一条命令

deploy.sh:

#!/usr/bin/env bash
set -euo pipefail

HOST="[email protected]"
REMOTE="/var/www/dudao"
STAMP="$(date +%Y%m%d-%H%M)"
TARGET="$REMOTE/releases/$STAMP"

npm run build

ssh "$HOST" "mkdir -p '$TARGET'"
rsync -az --delete dist/ "$HOST:$TARGET/"
ssh "$HOST" "ln -sfn '$TARGET' '$REMOTE/current' && sudo nginx -t && sudo systemctl reload nginx"

echo "已发布:$TARGET"
echo "回滚:ssh $HOST 'ln -sfn $REMOTE/releases/20261117-1015 $REMOTE/current'"

set -euo pipefail 三件事:任何命令失败就停(-e)、用到未定义变量就报错(-u)、管道里任一环失败都算失败(pipefail)。没有这三行,构建失败后脚本会继续把旧的 dist/ 推上去,你会在线上看到上一版还以为是新代码。

给执行权限并运行:

chmod +x deploy.sh
./deploy.sh

脚本里用了 sudo,需要该用户对 nginx 与 systemctl reload nginx 有免密权限。没有的话,把最后一行拆成手动执行,或按运维规范配一条精确的 sudoers 规则——不要图省事给 NOPASSWD: ALL。

清理旧版本,保留最近五个:

ssh [email protected] 'ls -1dt /var/www/dudao/releases/*/ | tail -n +6 | xargs -r rm -rf'

注意 current 指向的那版可能被删掉(如果它恰好排在第六个)。稳妥做法是先排除当前指向:

ssh [email protected] 'current=$(readlink -f /var/www/dudao/current); ls -1dt /var/www/dudao/releases/*/ | grep -v "^$current/$" | tail -n +6 | xargs -r rm -rf'

3.7.4 三个坑

坑 1:root 指错层级,整站 404

症状:curl -I 首页返回 500,而某个 JS 返回 404。error.log 里是:

rewrite or internal redirection cycle while internally redirecting to "/index.html"

成因:root 写成了 /var/www/dudao,而文件在 /var/www/dudao/current/index.html;或者反过来,root 写到了 current/dist,多了一层。首页找不到入口文件,try_files 回退到 /index.html,又找不到,于是循环到上限报 500。

修法:root 要指向"包含 index.html 的那一层"。本项目就是 /var/www/dudao/current。改完 nginx -t && systemctl reload nginx,再 curl -I 验证。

一个快速定位技巧:看 error.log 里那行"它到底去哪个路径找了"。Nginx 会把你配置推导出的完整路径打出来,一比就知道差在哪一层。

坑 2:403,日志里是 Permission denied

症状:

403 Forbidden

/var/log/nginx/error.log:

open() "/var/www/dudao/current/index.html" failed (13: Permission denied)

成因:文件或目录的属主/权限不对。最常见的是用 sudo rsync 或 sudo scp 推送,文件变成 root:root 且权限 600;Nginx 的 worker 进程以 www-data 运行,读不到。另一种是某一级目录缺 x 位——目录没有执行权限就无法进入,哪怕里面的文件是 644。

修法:

sudo chown -R www-data:www-data /var/www/dudao
sudo find /var/www/dudao -type d -exec chmod 755 {} \;
sudo find /var/www/dudao -type f -exec chmod 644 {} \;

更彻底的做法是从源头避免:用普通用户推送,目录归属设成 你的用户:www-data,rsync 加 --chmod=D755,F644。永远不要用 root 跑发布脚本——它会把权限问题留到线上才暴露。

坑 3:发版成功,用户还看旧页面

症状:curl -I 看到的是新内容,浏览器里还是旧版;用户反馈"按钮点了没反应",其实他加载的是三天前的 JS。

成因:index.html 被设了长缓存(比如 expires 1y),或者套了 CDN 且缓存规则没排除 HTML。浏览器直接用了缓存里的旧 index.html,里面引用的还是旧哈希的 JS——而旧 JS 可能已经被 --delete 删掉了,于是 404,页面白屏。

修法:确认 index.html 返回 Cache-Control: no-cache,/assets/ 才是长缓存。已经有用户被缓存住时,让他强制刷新一次(Ctrl + F5)即可恢复,之后新规则生效。

自检方法:curl -I 看响应头,而不是看页面。响应头是服务器的真实回答,页面是浏览器加工后的结果。

本章验收

  • 服务器上有 releases/<时间戳>/ 至少两个版本,current 指向最新那个
  • curl -I http://你的地址/ 返回 200,且 Cache-Control 是 no-cache
  • curl -I .../assets/xxx.js 返回 200,Cache-Control 含 immutable
  • 能在不重新构建的情况下,用一条 ln -sfn 把线上切回上一版,并验证成功
  • ./deploy.sh 一条命令完成构建、上传、切链、reload
  • 能说出 403 / 404 / 500 各查哪里,以及 502 为什么在纯静态站不会出现

自测

Q1:为什么发布用"新目录 + 切软链",而不是直接覆盖旧目录里的文件?

看答案 覆盖不是原子操作,传输中断会留下半新半旧的文件,`index.html` 可能引用一个还没传上去的 JS,用户直接白屏;而且旧版本被破坏后无法快速回退。新目录方式每次发布都是完整的一份,切软链是原子操作,回滚只是把链接指回去,不需要重新构建或传输。

Q2:try_files $uri $uri/ /index.html 会给静态资源带来什么副作用?怎么修?

看答案 不存在的 JS/CSS 也会命中最后的回退,返回 `index.html` 的内容和 `200` 状态码,浏览器按模块脚本解析时发现 MIME 是 `text/html`,报 `Expected a JavaScript-or-Wasm module script but the server responded with a MIME type of "text/html"`。修法是在 `location /assets/` 里单独写 `try_files $uri =404;`,让资源缺失返回真正的 404,便于定位。

Q3:curl -I 显示 200,但用户说打不开。你先怀疑什么?

看答案 先怀疑缓存与网络路径差异:用户可能拿到的是缓存的旧 `index.html`,引用了已被删除的旧哈希资源,于是白屏;也可能他访问的是另一个地址(带 www、http/https 混用、CDN 节点未刷新)。所以要让用户提供准确 URL 与截图,并用 `curl -I` 分别验证 HTML 与具体资源,而不是只看首页状态码。

下一步

卷 3 到此收口:代码有历史、依赖可复现、产物可发布、版本可回滚。但「读到」还是手写 DOM,加一个页面就要复制一遍渲染逻辑。下一卷换 React 与 Next,把这些重复劳动交给组件。

→ ../卷4/卷4-01-为什么需要框架.md