在 vite 项目中配置 cdn 部署，核心做法是修改 `vite.config.js` 中的 `build.rollupoptions.output.assetfilenames` 和 `build.minify` 等选项，将构建产物（js、css、图片）输出到指定目录并生成对应的 html 引用路径。这样做可以将静态资源与服务器端渲染的 html 分离，便于通过 nginx 或对象存储（如 aws s3、阿里云 oss）进行分发。若遇到资源加载失败，通常是因为相对路径未正确转换为绝对 cdn url，需确保 `base` 配置与 cdn 根路径一致。
Vite 构建时如何自定义资源输出路径
要解决资源路径问题，需在 `vite.config.js` 中重写 `assetFileNames` 钩子，将哈希文件名映射到 CDN 目录结构。例如，将所有 `.js` 文件输出到 `/cdn/assets/js/` 目录下，CSS 输出到 `/cdn/assets/css/`。这样构建后，HTML 中的 `<script>` 和 `<link>` 标签会自动引用这些新路径。关键在于使用 `[name]-[hash][extname]` 格式保留文件名以便缓存，同时通过 `resolveUrl` 函数动态拼接 CDN 前缀。</script>
import { defineConfig } from 'vite';
import path from 'path';
export default defineConfig({
base: '/cdn/', // 设置基础路径为 CDN 根目录
build: {
rollupOptions: {
output: {
assetFileNames: (assetInfo) => {
const extType = assetInfo.name.split('.').pop();
if (/\.(png|jpe?g|gif|svg)$/.test(extType)) {
return 'assets/images/[name]-[hash][extname]';
}
if (/\.(css)$/.test(extType)) {
return 'assets/css/[name]-[hash][extname]';
}
return 'assets/js/[name]-[hash][extname]';
},
// 可选：手动生成 manifest.json 用于服务端映射
manualChunks: undefined
}
},
minify: 'terser'
}
});运行 `npm run build` 后，查看 `dist` 目录，你会发现所有静态资源都按照配置的子目录结构排列。此时生成的 `index.html` 中的引用路径已自动更新为 `/cdn/assets/js/main-xxx.js` 等形式。这种配置方式直接改变了构建产物的物理结构和 HTML 中的引用字符串，是实现 CDN 部署的第一步。
立即学习“Java免费学习笔记（深入）”；
如何验证构建后的资源引用是否正确
验证的关键在于检查生成的 `index.html` 源码以及浏览器控制台的网络请求。构建完成后，打开 `dist/index.html`，确认所有 `<script src="...">` 和 `<link href=...>` 是否以配置的 `base` 路径开头。如果本地预览出现 404 错误，通常是因为开发服务器默认使用 `/` 作为 base，而生产环境需要显式指定。此外，可以使用 `vite preview` 命令启动一个本地预览服务器，模拟生产环境的目录结构，确保资源加载无误。</script>
// 验证脚本：检查 dist/index.html 中的资源路径
const fs = require('fs');
const path = require('path');
const htmlPath = path.join(__dirname, 'dist', 'index.html');
const htmlContent = fs.readFileSync(htmlPath, 'utf-8');
// 提取所有 script 和 link 标签的 src/href
const regex = /(?:src|href)=['"]([^'"]+)['"]/g;
let match;
const issues = [];
while ((match = regex.exec(htmlContent)) !== null) {
const url = match[1];
if (!url.startsWith('/cdn/') && !url.startsWith('http')) {
issues.push(`Invalid path: ${url}`);
}
}
if (issues.length > 0) {
console.error('CDN Path Issues:', issues);
} else {
console.log('All paths are correctly configured for CDN.');
}执行上述 Node.js 脚本，它会遍历 `dist/index.html` 中的所有资源引用。如果所有路径都以 `/cdn/` 开头，说明配置生效。若发现相对路径（如 `./assets/...`），则说明 `base` 配置未生效或构建插件未正确处理路径替换。此步骤确保了从构建端到部署端的链路畅通，避免了因路径错误导致的白屏问题。
当使用 Nginx 反向代理时如何处理 404 错误
在 Nginx 配置中，如果直接指向 `dist` 目录，可能会因为 SPA 路由导致非资源文件请求返回 404。解决方法是在 Nginx 配置中添加 `try_files` 指令，将未知请求重定向到 `index.html`。同时，对于 CDN 上的静态资源，应设置长期缓存头。例如，配置 `location /cdn/` 指向静态文件目录，并设置 `expires 1y`；配置 `location /` 指向 `index.html` 并启用 `try_files $uri $uri/ /index.html;`。这样，浏览器在刷新页面时能正确加载应用，而静态资源则由 Nginx 高效分发。
server {
listen 80;
server_name example.com;
root /var/www/dist;
index index.html;
# 静态资源缓存
location /cdn/ {
expires 1y;
add_header Cache-Control "public, immutable";
}
# SPA 路由支持
location / {
try_files $uri $uri/ /index.html;
}
}此配置解决了两个常见问题：一是静态资源的缓存策略，二是 SPA 的路由回退。当用户直接访问 `/about` 这样的路由时，Nginx 会返回 `index.html`，前端路由接管后正常显示内容。而 `/cdn/assets/js/main-xxx.js` 这样的请求则直接由 Nginx 读取文件并返回，无需经过应用逻辑。这种组合配置是 Vite 项目 CDN 部署的标准实践，确保了性能和用户体验的双重优化。
