nginx前端部署与Vite环境变量配置指南

一、nginx

Nginx 是一款高性能的 HTTP 和反向代理服务器，对于前端开发者而言，它是在生产环境部署和交付应用的关键工具。它能高效地托管你的静态资源，并作为中间层解决前后端协同工作中的常见问题

。

下面这个表格清晰地展示了 Nginx 在前端部署中的核心价值：

核心功能	对前端部署的意义	关键配置指令示例
静态资源服务	高效托管 HTML、CSS、JS、图片等文件，提升访问速度	`root`, `index`, `try_files`
反向代理	解决前端直接调用后端 API 的跨域问题，实现前后端解耦	`proxy_pass`, `proxy_set_header`
负载均衡	在高流量场景下，将请求分发到多个前端服务器实例，提升应用可用性	`upstream`, 负载均衡策略（如 `weight`）
SPA路由处理	保证单页应用在浏览器直接访问子路由或刷新时不返回 404 错误	`try_files $uri $uri/ /index.html;`

深入理解代理方向

理解"正向"和"反向"的关键在于搞清代理关系中的服务对象。

正向代理：替客户端办事

它站在客户端一边，是客户端的"代言人"。客户端明确知道自己使用了代理（比如在浏览器或系统设置中配置了代理服务器地址），并通过它去访问外部资源。对于目标服务器来说，请求来自于代理服务器，而非真实的客户端，从而隐藏了客户端的信息

。你例子中的VPN就是非常典型的正向代理。
反向代理：替服务端办事

它站在服务端一边，是服务器的"保护壳"和"调度中心"。客户端通常不知道反向代理的存在，它以为自己在直接访问目标网站（比如 www.baidu.com）。反向代理接收所有请求，然后按照一定规则（如负载均衡）将请求转发给内部的后端服务器集群，最后将结果返回给客户端。这样做隐藏了真实的服务器信息，提升了站点的安全性、可用性和性能

。你提到的百度多个服务器，正是通过反向代理来统一对外服务的。
🛠️ 反向代理的核心功能

你提到了反向代理用于代理访问，这是对的。除此之外，它在现代网站架构中还承担着几个极其重要的角色

：

负载均衡：这是反向代理最核心的功能之一。当网站访问量巨大时，一台服务器无法承受。反向代理可以将并发请求均匀地分发给后台多台服务器，避免任何一台服务器过载，从而保证应用的可用性和响应速度

。

安全保障：通过隐藏真实的后端服务器，反向代理在公网和内部服务器之间建立了一个屏障，有效防止了直接对后端服务器的攻击，增强了安全性

。

性能提升：反向代理可以缓存静态内容（如图片、CSS文件），当再次有相同请求时，直接返回缓存结果，减轻后端服务器压力，加快客户端访问速度

。它还可以统一处理SSL/TLS加密解密（即SSL终端），减轻后端服务器的计算负担

。
💎 总结

可以这样简单概括：

正向代理是我们（客户端）的代理，帮我们"翻出去"或隐藏自己。

反向代理是网站（服务器）的代理，帮网站"扛住"高并发流量并保护自己。

二、常见问题

1. 为什么本地项目跑起来之后能和线上的数据保持一致？

比如跑起来的本地服务是http://localhost:8090/，

解释：主要分两个方面去考虑，一个是静态前端文件，一个是数据渲染，前端文件是构建生成的，主要是渲染数据，渲染是通过前端做转发

1.1 比如/api/caiwu 转发到服务http://10.8.17.5:1125,这个时候就会去对应的端口去渲染数据，我们也可以在cmd中去ping 服务名。看服务是否正常工作

1.2 在vue3+vite项目中，通常在env.development中设置开发调试相关的配置

javascript 复制代码

# 打包后静态资源前缀
VITE_PUBLIC_PATH = /

# Basic interface address SPA
VITE_GLOB_API_URL = /api

2. 本地和线上环境的界面内容是一样?线上环境和本地连接的区别是什么？

线上环境的配置是本地的前端静态文件打包到服务器目录中，然后进行后端服务转发

比如nginx配置

javascript 复制代码

 #系统DEV
    server {
        listen    8056;
        charset   utf-8;
        server_name  localhost;
                            
        location  / {
            alias 前端静态文件存放路径
            index  index.html index.htm;
            try_files $uri $uri/ /index.html;
        }

        location ^~/api/pc/caiwu/ {
            proxy_pass  后端服务;
            proxy_redirect      off;
            proxy_set_header    Host $http_host;
            proxy_set_header    X-Real-IP $remote_a
       location ^~/api/caiwu/ {
            proxy_pass  后端服务;
            proxy_redirect      off;
            proxy_set_header    Host $http_host;
            proxy_set_header    X-Real-IP $remote_a

3. 环境变量配置

.env.development

javascript 复制代码

# 打包后静态资源前缀
VITE_PUBLIC_PATH = /

# Basic interface address SPA
VITE_GLOB_API_URL = /api

.env.production

javascript 复制代码

# 打包后静态资源前缀
VITE_PUBLIC_PATH = ./

# Basic interface address SPA
VITE_GLOB_API_URL = /api/pc

.env.staging

javascript 复制代码

# 打包后静态资源前缀
VITE_PUBLIC_PATH = ./

# Basic interface address SPA
VITE_GLOB_API_URL = /api/pc

.env.development: 用于开发调试

.env.production:用于部署线上正式环境

.env.staging：用于部署线上测试环境

3.1 . VITE_PUBLIC_PATH 的差异

开发环境（development）

javascript 复制代码

VITE_PUBLIC_PATH = /

该配置表示打包后的静态资源（如图片、字体等）路径以根路径 / 为前缀。

作用：在本地开发环境中，通常通过根路径直接访问资源，避免因本地服务器配置问题导致的路径错误。

生产/测试环境（production/staging）

javascript 复制代码

VITE_PUBLIC_PATH = ./

该配置表示静态资源路径以当前页面的相对路径 ./ 为前缀。

作用：

在生产环境部署时，若应用被部署到子目录（例如 https://example.com/my-app/），使用相对路径可确保静态资源正确加载。

避免因服务器配置或部署路径变化导致的路径问题。

3.2 . VITE_GLOB_API_URL 的差异

开发环境（development）

javascript 复制代码

VITE_GLOB_API_URL = /api

表示接口请求的基路径为 /api，即直接通过根路径访问后端接口。

作用：在本地开发环境中，通常通过代理或直接请求后端服务的根路径（如 http://localhost:3000/api）。

生产/测试环境（production/staging）

javascript 复制代码

VITE_GLOB_API_URL = ./api

表示接口请求的基路径为 ./api（相对路径）。

作用：
若生产环境部署到子目录 （如 https://example.com/my-app/），接口请求会指向 https://example.com/my-app/api，确保与后端路径匹配。

避免跨域问题（CORS），因相对路径会基于当前页面的域名和路径构造请求。

总结：

开发环境需直接访问根路径；生产环境需适配部署路径。

开发环境通过根路径调用接口；生产环境如部署到子目录，需适配相对路径./api，如果部署到根目录，则/api

三、部署路径类型与API路径配置

1.1 部署路径类型

根目录部署 ：应用部署在服务器根路径 /
子目录部署 ：应用部署在服务器子路径（如 /mobiBiz）

1.2 VITE_GLOB_API_URL配置规则

部署类型	推荐配置	解析结果示例
根目录	`VITE_GLOB_API_URL = /api`	请求路径：`/api/business`
子目录	`VITE_GLOB_API_URL = ./api`	请求路径：`/mobiBiz/api/business`

二、Vite环境变量核心配置

2.1 关键环境变量

language 复制代码

  // ... existing code ...

  # 静态资源前缀（必须与部署路径匹配）
  VITE_PUBLIC_PATH = ./ 

  # API基础路径（根据部署类型动态调整）
  VITE_GLOB_API_URL = {{ "./api" | "/" }}

  // ... rest of code ...

2.2 开发环境代理配置

language 复制代码

  // ... existing code ...

  # 代理规则示例（开发环境模拟生产路径）
  VITE_PROXY = [
    ["/api/auth/login", "http://backend/api/auth/login"],
    ["/mobiBiz/api", "http://backend/mobiBiz/api"]
  ]

  // ... rest of code ...

四、Nginx配置与代理规则

3.1 子目录部署配置

nginx 复制代码

server {
  listen 80;
  server_name example.com;

  # 子目录部署路径配置
  location /mobiBiz {
    root /var/www/frontend/dist;
    index index.html;
    try_files $uri $uri/ /mobiBiz/index.html;
  }

  # API代理规则（关键）
  location ^~ /mobiBiz/api {
    proxy_pass http://backend_server/api;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
  }
}

3.2 根目录部署配置

nginx 复制代码

server {
  listen 80;
  server_name example.com;

  # 根目录部署路径配置
  location / {
    root /var/www/frontend/dist;
    index index.html;
    try_files $uri $uri/ /index.html;
  }

  # API代理规则
  location /api {
    proxy_pass http://backend_server/api;
    # ...其他代理配置...
  }
}

五、路径解析验证

4.1 子目录部署路径验证

javascript 复制代码

// 请求路径示例
fetch(`${import.meta.env.VITE_GLOB_API_URL}/business`)
// → 解析为：/mobiBiz/api/business

4.2 Nginx代理匹配验证

nginx 复制代码

# 当请求 /mobiBiz/api/business 时：
# Nginx匹配到 location ^~ /mobiBiz/api 规则
# 代理到后端服务的 /api/business 接口

六、常见问题与解决方案

5.1 路径404错误排查

问题：API请求返回404
原因：VITE_GLOB_API_URL配置与部署路径不匹配

解决方案 ：

diff 复制代码

# 错误配置（子目录部署）
- VITE_GLOB_API_URL = /api
# 正确配置
+ VITE_GLOB_API_URL = ./api

5.2 开发环境代理冲突

问题：开发环境请求被浏览器直接访问
原因：未在vite.config.js中配置代理

解决方案 ：

javascript 复制代码

// vite.config.js
export default defineConfig({
  server: {
    proxy: {
      '/api': 'http://backend_server/api',
    }
  }
})

七、最佳实践总结

路径一致性原则

VITE_PUBLIC_PATH与VITE_GLOB_API_URL需保持路径层级一致

示例：

复制代码

VITE_PUBLIC_PATH = ./ → VITE_GLOB_API_URL = ./api  
VITE_PUBLIC_PATH = / → VITE_GLOB_API_URL = /api

代理规则优先级
- 使用^~修饰符确保精确匹配子目录路径
- 示例：location ^~ /mobiBiz/api优先于普通/api规则
环境变量隔离
- 严格区分.env.development与.env.production配置
- 开发环境通过VITE_PROXY模拟代理，生产环境依赖Nginx配置