前端部署到服务器后如何交付

文章导读
把前端部署到服务器之后,“交付”通常不是指文件传上去了,而是指三件事同时成立:静态文件落在 Nginx 配置的 root 下、访问域名返回的是这份文件、刷新任意前端路由也能回到 index.html。这三件事各有可核对的落点:ls 看文件与时间戳,nginx -T 看生效配置,curl -I 看响应头和状态码。缺哪一项,问题就出在哪一段,不需要凭感觉猜。
📋 目录
  1. 一 前端部署到服务器Nginx
  2. 二 前端部署到服务器的步骤
  3. 三 前端部署到服务器:先把能核对的事实摆清楚
  4. 四 前端部署到服务器最容易搞错的一点
  5. 五 前端部署到服务器:一个照着就能做完的做法
A A

把前端部署到服务器之后,“交付”通常不是指文件传上去了,而是指三件事同时成立:静态文件落在 Nginx 配置的 root 下、访问域名返回的是这份文件、刷新任意前端路由也能回到 index.html。这三件事各有可核对的落点:ls 看文件与时间戳,nginx -T 看生效配置,curl -I 看响应头和状态码。缺哪一项,问题就出在哪一段,不需要凭感觉猜。

前端交付的判断顺序建议固定为:先确认服务器上存在本次构建产物(看文件时间戳),再确认 Nginx 加载的配置里 root 指向该目录,最后用 curl 打回环地址看状态码和 Content-Type。回环地址能通而域名不通,问题在 CDN、DNS 或反向代理层,不在静态文件本身。子目录部署时,构建工具的 base 与 Nginx 的 location 必须同时改,只改一边会出现白屏或资源 404。

前端部署到服务器Nginx

这一段对应的是“文件托管与路由回退”,即 Nginx 负责把磁盘上的静态文件和浏览器请求对上。确认是不是这一段出了问题,最快的办法是绕开域名直接打本机回环地址,排除 DNS、CDN 和上层反向代理的干扰。

curl -sI http://127.0.0.1/ | head -n 5
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1/order/123
sudo nginx -T | grep -nE 'root|try_files|server_name'
sudo tail -n 30 /var/log/nginx/error.log

判断依据很直接:curl -I 返回 200 且 Content-Type: text/html,说明 Nginx 找到了文件;返回 404 说明 root 指错目录或文件名不匹配,此时 error.log 里会打印 Nginx 实际去读的绝对路径,把那个路径和 ls 的结果对一遍就能定位。nginx -T 输出的是真正生效的配置合并结果,比自己翻 sites-enabled 更可靠,因为同一端口可能被另一份配置先匹配走。

前端部署到服务器的步骤

这一段对应“产物上传与目录切换”,即从本地 dist 到服务器目标目录的搬运,以及 Nginx 指向新目录。确认是不是这一段,看产物时间戳和权限,而不是看构建日志有没有报错。

前端部署到服务器后如何交付
ls -l /var/www/app/current/index.html
find /var/www/app -maxdepth 3 -name 'index.html' -printf '%p %TY-%Tm-%Td %TH:%TM\n'
namei -l /var/www/app/current/index.html
sudo nginx -t && systemctl is-active nginx

find 打印的时间应该是本次构建的时间;如果还是上一版的时间,说明压缩包解到了别的目录,或者 current 这个软链没有切换。namei -l 逐级列出路径权限,Nginx 工作进程(通常是 www-data 或 nginx 用户)需要对每一级目录至少有执行权限,某一级是 700 就会出现“文件明明在、访问却 403”,这个现象在 error.log 里会明确写成 Permission denied。

前端部署到服务器:先把能核对的事实摆清楚

下结论之前,先把四类可核对的事实摆出来,不要混在一起讨论。

  • 对象:服务器上的静态目录(例如 /var/www/app/current)、Nginx 配置文件及其 include 链、域名或 IP 的解析结果。
  • 前提:Nginx 已启动并 reload 过;构建产物已完整上传(含 index.html 和资源目录);部署路径与构建时的 base 一致。
  • 现象一:浏览器打开是白屏,但 view-source 里能看到 index.html 内容,通常是资源路径前缀不对,可在 Network 面板看资源请求的完整 URL。
  • 现象二:首页正常、刷新子路由 404,是 try_files 缺少回退到 /index.html 的规则。
  • 现象三:返回 403 或 500,去 /var/log/nginx/error.log 找同时间戳的记录,那里写的是真实原因。

这些事实在没有对照之前不要合并成“部署失败”一个结论。域名解析、证书、上层代理各自有独立的核对方法,通常会先确认回环地址能通,再去查域名这一层。

前端部署到服务器后如何交付

前端部署到服务器最容易搞错的一点

最常见的误解是把“首页能打开”当成“部署完成”。首页能打开只证明 index.html 被取到了,不证明前端路由回退和资源路径正确。判断分界在于:直接访问一个前端路由(如 /order/123)和直接访问一个带哈希的资源文件,两者的响应是否都符合预期。

curl -s -o /dev/null -w 'home:%{http_code}\n' http://127.0.0.1/
curl -s -o /dev/null -w 'route:%{http_code}\n' http://127.0.0.1/order/123
curl -sI http://127.0.0.1/assets/ | head -n 3

如果 home 是 200 而 route 是 404,说明是路由回退问题,去补 try_files;如果两个都是 404,是目录指向问题,先改 root。这两类问题的修法完全不同,先跑这两条命令再动手,能省掉反复试错。

前端部署到服务器:一个照着就能做完的做法

下面是一条从构建到验证的完整路径,命令按顺序执行即可。目录名和域名是占位,按实际环境替换。

前端部署到服务器后如何交付
# 1) 本地构建(以 Vite 为例,子目录部署时加 base)
npm ci
npm run build

tar -czf dist.tar.gz -C dist .

# 2) 上传到服务器临时目录
scp dist.tar.gz deploy@your-server:/tmp/dist.tar.gz

# 3) 服务器上解到新目录,不直接覆盖线上目录
ssh deploy@your-server
RELEASE=/var/www/app/releases/$(date +%Y%m%d%H%M%S)
sudo mkdir -p "$RELEASE"
sudo tar -xzf /tmp/dist.tar.gz -C "$RELEASE"
sudo chown -R www-data:www-data "$RELEASE"

# 4) 切换软链,current 永远指向最新一次发布
sudo ln -sfn "$RELEASE" /var/www/app/current
ls -l /var/www/app/current/index.html

Nginx 配置里固定指向 current,发布时只切软链,不用改配置:

server {
    listen 80;
    server_name example.com;

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

    location /assets/ {
        expires 7d;
        add_header Cache-Control "public";
    }

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

每一步该看到什么:执行 nginx -t 应输出 syntax is ok 与 test is successful,再 sudo systemctl reload nginx;随后 curl -sI http://127.0.0.1/ 应返回 200 和 Content-Type: text/html;curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1/order/123 在配置了 try_files 后应从 404 变为 200;最后访问一次静态资源,确认 Last-Modified 与本次发布时间一致。

几点边界需要结合环境确认:index.html 不建议长缓存,带哈希的资源文件才可以设长 expires;子目录部署时构建工具的 base 和 Nginx 的 location 前缀要同时改,只改一边会出现白屏;try_files 只是路由回退,不解决接口请求,前后端分离时 /api 仍需单独 location 转发。软链方案在部分启用 disable_symlinks 的机器上会被拦截,遇到 403 时先查该项配置。