前端工程化 / 系统课时
处理部署基础路径与回退
处理部署基础路径与回退
本课解决构建成功但上线后白屏、资源 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}

按模式生成 base
配置文件本身不会自动获得 .env.* 中的自定义变量,因此这里用 loadEnv 读取 APP_BASE。生产模式默认部署到 /console/,CDN 模式改用完整资源前缀。
// 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',
},
}
})# .env.production
APP_BASE=/console/# .env.cdn
APP_BASE=https://cdn.example.com/app/片段示例:应用代码中如果要拼接 public/ 目录下的文件,应把下面代码放在浏览器端模块中,并保留 Vite 可静态识别的完整变量名:
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 中提取入口脚本地址:
npm run build
grep -oE 'src="[^"]+\.js"' dist/index.html
npm run build -- --mode cdn
grep -oE 'src="[^"]+\.js"' dist/index.html预期输出:
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/ 请求只有在找不到真实文件时才回退到应用入口。
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:
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'预期输出:
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}
npm run preview -- --host 127.0.0.1 --port 4173 --strictPort预期输出:
Local: http://127.0.0.1:4173/console/实际日志可能带图标或额外提示,但访问路径应包含 /console/。完成本地检查后,仍要在真实域名上分别测试入口、深层路由、已存在资源和不存在资源。
排障顺序
先查看 dist/index.html 中的 src 与 href:前缀错误属于构建配置问题。再直接请求资源 URL:返回 404 表示发布目录或 CDN 路径不一致,返回 HTML 表示回退规则吞掉了资源错误。
最后直接刷新一个深层前端路由。只有深层路由 404 时,问题在服务器回退;preview 可用而真实域名失败时,重点比较部署根目录、代理前缀、CDN 上传位置和缓存中的旧 HTML。