前端工程化 / 系统课时

处理部署基础路径与回退

处理部署基础路径与回退

本课解决构建成功但上线后白屏、资源 404 或刷新路由失败的问题。你将把部署目录、CDN 前缀和 Vite 的 base 对齐,再为单页应用配置服务器回退,并用构建产物与 HTTP 响应验证真实部署行为。

学习目标

  • 根据域名根目录、子目录或 CDN 场景选择正确的 base
  • 验证 HTML 中生成的资源地址与运行时拼接地址
  • 为 SPA 配置只回退页面请求、不吞掉静态资源错误的规则

先确定公开基础路径

base 是应用对外发布时的公共前缀。Vite 构建会据此重写 HTML 资源、JavaScript 导入资源和 CSS url();运行时手工拼接公开文件地址时,应直接使用 import.meta.env.BASE_URL。该变量会在构建时静态替换,必须保持这一完整写法。:contentReference[oaicite:3]{index=3}

部署位置 推荐 base 生成地址示例
域名根目录 / /assets/index-<ID>.js
域名子目录 /console/ /console/assets/index-<ID>.js
独立 CDN 前缀 https://cdn.example.com/app/ https://cdn.example.com/app/assets/index-<ID>.js
最终目录未知的嵌入式部署 ./ ./assets/index-<ID>.js

路径型和完整 URL 型 base 都应保留结尾斜杠。相对 base 适合文件位置可能变化的静态包,但依赖运行环境正确支持 import.meta,也不等于自动解决前端路由回退。:contentReference[oaicite:4]{index=4}

基础路径、CDN 资源与路由回退数据流

按模式生成 base

配置文件本身不会自动获得 .env.* 中的自定义变量,因此这里用 loadEnv 读取 APP_BASE。生产模式默认部署到 /console/,CDN 模式改用完整资源前缀。

ts
// vite.config.ts
import { defineConfig, loadEnv } from 'vite'

export default defineConfig(({ mode }) => {
  const env = loadEnv(mode, process.cwd(), '')

  return {
    base: env.APP_BASE || '/',
    build: {
      outDir: 'dist',
    },
  }
})
text
# .env.production
APP_BASE=/console/
text
# .env.cdn
APP_BASE=https://cdn.example.com/app/

片段示例:应用代码中如果要拼接 public/ 目录下的文件,应把下面代码放在浏览器端模块中,并保留 Vite 可静态识别的完整变量名:

ts
const helpUrl = `${import.meta.env.BASE_URL}help/index.html`

不要改写成 import.meta.env['BASE_URL'],也不要在源码中硬编码 /console/,否则同一份代码无法随构建模式切换。Vite 会自动处理被导入的资源,只有运行时自行拼接的 URL 才需要显式使用 BASE_URL。:contentReference[oaicite:5]{index=5}

构建并检查资源地址

项目的 package.json 需包含 "build": "vite build"。下面先构建子目录版本,再构建 CDN 版本,并从生成的 HTML 中提取入口脚本地址:

bash
npm run build
grep -oE 'src="[^"]+\.js"' dist/index.html
npm run build -- --mode cdn
grep -oE 'src="[^"]+\.js"' dist/index.html

预期输出:

text
src="/console/assets/index-<ID>.js"
src="https://cdn.example.com/app/assets/index-<ID>.js"

<ID> 是内容哈希,实际值会随源码变化。第一行前缀错误时先修复 .env.production 并重新构建;第二行正确但浏览器仍 404 时,应检查 CDN 是否把 dist/assets/ 发布到了与前缀一致的目录。

在真实服务器配置 SPA 回退

下面以 Nginx 为例,假设 dist 内容已复制到 /srv/www/app/console/。静态资源路径先单独匹配,文件不存在就返回 404;其余 /console/ 请求只有在找不到真实文件时才回退到应用入口。

nginx
server {
  listen 8080;
  server_name _;
  root /srv/www/app;

  location ^~ /console/assets/ {
    try_files $uri =404;
    add_header Cache-Control "public, max-age=31536000, immutable";
  }

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

重新加载 Nginx 后,验证深层路由返回 HTML,真实脚本返回 JavaScript:

bash
ASSET=$(basename "$(find /srv/www/app/console/assets -name '*.js' | head -n 1)")
curl -sSI http://localhost:8080/console/orders/42 | grep -E 'HTTP/|Content-Type'
curl -sSI "http://localhost:8080/console/assets/$ASSET" | grep -E 'HTTP/|Content-Type'

预期输出:

text
HTTP/1.1 200 OK
Content-Type: text/html
HTTP/1.1 200 OK
Content-Type: application/javascript

若缺失脚本也返回 text/html,说明回退范围过宽,浏览器通常会报模块 MIME 类型错误。多页面应用则应优先发布真实 HTML 路径,不要把所有页面请求都强制回退到同一个入口。

区分 preview 与生产服务器

vite preview 只用于本地查看 dist,不是生产服务器。它可以发现构建产物是否能加载,却不会替你验证 CDN 发布目录、Nginx 回退、TLS、缓存头或反向代理前缀,因此“preview 正常、线上失败”通常仍是部署层问题。:contentReference[oaicite:6]{index=6}

bash
npm run preview -- --host 127.0.0.1 --port 4173 --strictPort

预期输出:

text
Local: http://127.0.0.1:4173/console/

实际日志可能带图标或额外提示,但访问路径应包含 /console/。完成本地检查后,仍要在真实域名上分别测试入口、深层路由、已存在资源和不存在资源。

排障顺序

先查看 dist/index.html 中的 src 与 href:前缀错误属于构建配置问题。再直接请求资源 URL:返回 404 表示发布目录或 CDN 路径不一致,返回 HTML 表示回退规则吞掉了资源错误。

最后直接刷新一个深层前端路由。只有深层路由 404 时,问题在服务器回退;preview 可用而真实域名失败时,重点比较部署根目录、代理前缀、CDN 上传位置和缓存中的旧 HTML。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

处理部署基础路径与回退

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通