Vite项目Nginx子路径部署全攻略

你是否曾遇到Vite项目部署到Nginx子路径后页面空白、资源加载失败或路由刷新404的问题？本文将通过3步配置法+故障排除指南，彻底解决这些痛点。读完你将掌握：

• Vite配置文件的关键参数设置
• Nginx服务器的精确路由规则
• 静态资源路径的自动适配方案
• 404错误的终极解决办法

1. Vite项目配置（核心步骤）

1.1 设置base路径

打开项目根目录的vite.config.js文件，添加base配置项指定子路径名称：

export default defineConfig({
  base: '/vite-app/',  // 子路径名称，必须以/开头和结尾
  // 其他配置...
})

⚠️ 注意：base值必须与Nginx配置中的location路径完全一致。例如Nginx配置/app/，则此处必须设为/app/。

1.2 构建生产版本

执行构建命令生成优化后的静态文件：

npm run build  # 构建产物默认输出到dist目录

构建完成后，检查dist/index.html文件，确认所有资源引用路径已自动加上/vite-app/前缀。

2. Nginx服务器配置

2.1 基础配置模板

在Nginx配置文件（通常位于/etc/nginx/conf.d/目录）中添加以下配置：

server {
    listen 80;
    server_name yourdomain.com;  # 替换为你的域名

    # 子路径部署核心配置
    location /vite-app/ {
        alias /path/to/your/vite/dist/;  # 替换为实际dist目录绝对路径
        try_files $uri $uri/ /vite-app/index.html;  # 解决SPA路由刷新404问题
        
        # 缓存控制 - 静态资源长期缓存
        location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2)$ {
            expires 30d;
            add_header Cache-Control "public, max-age=2592000";
        }
    }
}

2.2 配置说明

配置完成后，执行以下命令使配置生效：

nginx -t  # 测试配置是否有误
systemctl reload nginx  # 平滑重启Nginx

3. 部署验证与故障排除

3.1 基本访问测试

在浏览器中访问 http://yourdomain.com/vite-app/，验证：

• 首页是否正常加载
• 点击导航后URL是否显示为 /vite-app/about 格式
• 刷新页面是否仍能正常显示

3.2 常见问题解决方案

问题1：静态资源404错误

原因：Vite构建的资源路径与Nginx配置不匹配
解决：检查vite.config.js中的base值是否与Nginx的location路径完全一致

问题2：路由刷新后404

原因：Nginx未配置SPA路由重定向
解决：确保try_files指令正确设置为 $uri $uri/ /vite-app/index.html

问题3：CSS/JS加载跨域

原因：Nginx未正确配置CORS头
解决：在location块中添加：

add_header Access-Control-Allow-Origin *;

4. 高级优化配置

4.1 启用Gzip压缩

在Nginx配置中添加压缩配置，减少传输体积：

gzip on;
gzip_types text/css application/javascript image/svg+xml;
gzip_min_length 1k;
gzip_comp_level 6;

4.2 配置HTTPS（推荐）

通过Let's Encrypt获取免费SSL证书后，配置HTTPS：

server {
    listen 443 ssl;
    server_name yourdomain.com;
    
    ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem;
    
    # 其他SSL配置...
    
    location /vite-app/ {
        # 同上配置...
    }
}

5. 部署架构参考

下图展示了Vite项目在Nginx子路径部署的完整架构：

总结与最佳实践

1. 配置同步原则：始终保持Vite的base配置与Nginx的location路径完全一致
2. 构建验证：每次修改配置后执行npm run build重新构建
3. 缓存策略：对静态资源设置长期缓存，对HTML设置不缓存
4. 版本控制：建议在子路径中包含版本号，如/vite-app/v2/，便于多版本共存

官方文档：docs/guide/static-deploy.md
配置示例：playground/backend-integration/vite.config.js

通过以上步骤，你的Vite项目将在Nginx子路径环境中稳定运行，同时具备优秀的性能和可维护性。

到此这篇关于Vite项目Nginx子路径部署全攻略的文章就介绍到这了,更多相关Vite Nginx子路径部署内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！