# 代理配置

<!-- Copyright (c) 2021-2026 小蚂蚁云团队 版权所有 -->

:::tip 说明
开发环境通过 Vite 代理转发 API 请求到后端 Django 服务，生产环境通过 Nginx 代理。代理配置由 `VITE_PROXY` 环境变量控制。
:::

## 开发环境代理

### Vite 配置

`vite.config.ts` 中通过 `createProxy` 工具函数解析 `VITE_PROXY` 环境变量生成代理配置：

```typescript
// vite.config.ts
import { createProxy } from './build/vite/proxy';

export default ({ command, mode }: ConfigEnv): UserConfig => {
    let VITE_PROXY: any = viteEnv.VITE_PROXY;
    if (!VITE_PROXY) VITE_PROXY = '[[]]';
    try {
        if (typeof VITE_PROXY === 'string') VITE_PROXY = JSON.parse(VITE_PROXY);
    } catch (e) {
        VITE_PROXY = [[]];
    }

    return {
        server: {
            host: true,
            port: VITE_PORT,
            proxy: createProxy(VITE_PROXY),
        },
    };
};
```

### 环境变量配置

`.env.development` 文件中配置代理规则（JSON 数组格式）：

```bash
# 格式：[["前缀","目标地址"]]
VITE_PROXY=[["/api","http://127.0.0.1:8000/"]]
```

`createProxy` 函数将此配置转换为 Vite 的 `server.proxy` 格式，自动添加 `changeOrigin: true` 等选项。

### 代理规则

```
前端请求: http://localhost:8001/api/example/page
代理转发: http://127.0.0.1:8000/api/example/page
```

`/api` 前缀的请求被代理到后端 `http://127.0.0.1:8000`，`changeOrigin: true` 修改请求头的 Host 为目标地址。

### 开发流程

```
1. 启动后端: python manage.py runserver (127.0.0.1:8000)
2. 启动前端: cd ui && pnpm dev (localhost:8001)
3. 浏览器访问 localhost:8001
4. API 请求自动代理到 127.0.0.1:8000
```

### 前端请求路径

前端 API 函数中的 URL 不含 `/api` 前缀：

```typescript
// src/api/tool/example.ts
export function getExamplePage(params?) {
    return http.request({
        url: '/example/page', // 实际请求：/api/example/page
        method: 'GET',
        params,
    });
}
```

`VAxios` 创建时配置了 `prefixUrl`，`beforeRequestHook` 自动拼接：

```typescript
// src/utils/http/axios/index.ts
const urlPrefix = globSetting.urlPrefix || '';

createAxios({
    prefixUrl: urlPrefix,  // '/api'
    requestOptions: {
        joinPrefix: true,
        urlPrefix: urlPrefix,  // '/api'
    },
});
```

最终请求路径：`/api` + `/example/page` = `/api/example/page`

## 生产环境代理

### Nginx 配置

```nginx
server {
    listen 80;
    server_name your-domain.com;

    # 前端静态文件
    location / {
        root /path/to/dist;
        index index.html;
        try_files $uri $uri/ /index.html; # SPA 路由回退
    }

    # API 代理
    location /api/ {
        proxy_pass http://127.0.0.1:8000/api/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # 超时配置
        proxy_connect_timeout 30s;
        proxy_read_timeout 60s;
        proxy_send_timeout 60s;
    }
}
```

### Nginx 代理说明

| 配置项 | 说明 |
|--------|------|
| `proxy_pass` | 转发目标地址 |
| `proxy_set_header Host` | 传递原始 Host |
| `proxy_set_header X-Real-IP` | 传递客户端真实 IP |
| `proxy_set_header X-Forwarded-For` | 传递代理链 IP |
| `proxy_set_header X-Forwarded-Proto` | 传递原始协议 |
| `proxy_connect_timeout` | 连接超时 |
| `proxy_read_timeout` | 读取超时 |

## 文件访问代理

上传文件的访问也需要代理：

```nginx
# 文件访问
location /uploads/ {
    proxy_pass http://127.0.0.1:8000/uploads/;
    proxy_set_header Host $host;

    # 静态文件缓存
    expires 7d;
    add_header Cache-Control "public, immutable";
}
```

:::tip 温馨提示
后端的文件访问地址需要与前端 `DJANGO_FILE_URL` 配置一致。开发环境为 `http://file.django.elevue`，生产环境需要配置为实际的文件服务域名。
:::

## 总结

开发环境通过 `VITE_PROXY` 环境变量配置 Vite 代理，`createProxy` 函数解析 JSON 格式的代理规则。前端 API 路径不含 `/api` 前缀，由 `VAxios` 的 `beforeRequestHook` 自动拼接。生产环境通过 Nginx 代理并配置超时、缓存等参数。