dibang-xiaoshou/FRONTEND_BUILD_CONFIG.md

前端打包环境变量配置说明

概述

在打包 Web 端和移动端之前，需要在项目根目录创建 .env.production 文件来配置生产环境变量。

---

Web 端 (art-design-pro)

1. 创建配置文件

在 art-design-pro 目录下创建 .env.production 文件：

cd art-design-pro
touch .env.production

2. 配置内容

# ============================================
# Web 前端生产环境配置
# ============================================

# API 地址（必需）
# 如果使用 Nginx 代理，建议使用相对路径 /api（推荐）
# 这样 Nginx 会自动将 /api 请求代理到后端 http://127.0.0.1:8000
VITE_API_URL=/api

# 如果需要直接访问后端（不推荐，会有跨域问题），使用完整 URL:
# VITE_API_URL=http://121.43.228.102:8000

# 应用版本号（可选）
VITE_VERSION=1.0.0

3. 说明

• VITE_API_URL（必需）:

  • 推荐值: /api - 使用相对路径，由 Nginx 代理到后端
  • 如果使用完整 URL，需要确保后端配置了 CORS 允许该域名
    

• VITE_VERSION（可选）: 应用版本号，用于显示在界面或日志中

4. 打包命令

cd art-design-pro
npm install
npm run build

打包后的文件在 art-design-pro/dist/ 目录。

---

移动端 (mobile-h5)

1. 创建配置文件

在 mobile-h5 目录下创建 .env.production 文件：

cd mobile-h5
touch .env.production

2. 配置内容

# ============================================
# H5 移动端生产环境配置
# ============================================

# API 地址（必需）
# 如果使用 Nginx 代理，建议使用相对路径 /api（推荐）
# 这样 Nginx 会自动将 /api 请求代理到后端 http://127.0.0.1:8000
VITE_API_URL=/api

# 如果需要直接访问后端（不推荐，会有跨域问题），使用完整 URL:
# VITE_API_URL=http://121.43.228.102:8000

3. 说明

• VITE_API_URL（必需）:
  • 推荐值: /api - 使用相对路径，由 Nginx 代理到后端
  • 如果使用完整 URL，需要确保后端配置了 CORS 允许该域名

注意: VITE_API_BASE_URL 仅用于开发环境的 Vite 代理配置，打包时不需要。

4. 打包命令

cd mobile-h5
npm install
npm run build

打包后的文件在 mobile-h5/dist/ 目录。

---

推荐配置（使用 Nginx 代理）

为什么推荐使用 /api？

1. 无跨域问题: 前后端同源，不需要处理 CORS
2. 统一管理: 通过 Nginx 统一管理 API 路由
3. 灵活切换: 可以轻松切换后端服务地址，无需重新打包前端
4. 安全性: 后端服务不直接暴露在公网

配置示例

Web 端 .env.production:

VITE_API_URL=/api
VITE_VERSION=1.0.0

移动端 .env.production:

VITE_API_URL=/api

Nginx 配置

Nginx 会自动将 /api 请求代理到后端：

location /api {
    proxy_pass http://127.0.0.1:8000;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

---

如果必须使用完整 URL

如果由于特殊原因需要使用完整 URL（不推荐），需要：

1. 配置后端 CORS:

   # backend/.env
   CORS_ORIGINS=http://121.43.228.102,https://your-domain.com
   

   1. 前端配置: ```bash

      Web 端

      VITE_API_URL=http://121.43.228.102:8000

   移动端

   VITE_API_URL=http://121.43.228.102:8000 ```

2. 防火墙: 确保后端 8000 端口对外开放（不推荐）

---

验证配置

1. 检查环境变量是否生效

在代码中打印环境变量（仅开发环境可见）：

// 开发环境运行时会显示
console.log('API URL:', import.meta.env.VITE_API_URL)

2. 打包后检查

打包后，环境变量会被编译到代码中。可以通过以下方式验证：

1. 查看打包后的 JS 文件，搜索 API 地址
2. 在浏览器中打开应用，查看网络请求的 URL

3. 测试 API 连接

1. 打开浏览器开发者工具
2. 查看 Network 标签
3. 执行一个 API 请求
4. 检查请求 URL 是否正确

---

常见问题

Q1: 打包后 API 请求还是指向 localhost？

A: 检查 .env.production 文件是否存在，以及 VITE_API_URL 是否正确配置。

Q2: 使用 /api 后，请求 404？

A: 检查 Nginx 配置是否正确，确保 /api 路径被正确代理到后端。

Q3: 跨域错误？

A:

• 如果使用 /api，不应该有跨域问题（同源）
• 如果使用完整 URL，需要配置后端 CORS

Q4: 如何为不同环境使用不同配置？

A:

• 开发环境: .env.development 或 .env
• 生产环境: .env.production
• 测试环境: .env.test

Vite 会根据 mode 自动加载对应的环境文件。

---

完整打包流程

Web 端

# 1. 进入项目目录
cd art-design-pro

# 2. 创建生产环境配置
cat > .env.production << EOF
VITE_API_URL=/api
VITE_VERSION=1.0.0
EOF

# 3. 安装依赖（如果还没安装）
npm install

# 4. 打包
npm run build

# 5. 上传到服务器
scp -r dist/* user@121.43.228.102:/iflytek/dibang/web/

移动端

# 1. 进入项目目录
cd mobile-h5

# 2. 创建生产环境配置
cat > .env.production << EOF
VITE_API_URL=/api
EOF

# 3. 安装依赖（如果还没安装）
npm install

# 4. 打包
npm run build

# 5. 上传到服务器
scp -r dist/* user@121.43.228.102:/iflytek/dibang/app/

---

总结

1. 必需配置: 两个项目都需要配置 VITE_API_URL
2. 推荐值: /api（使用 Nginx 代理）
3. 配置文件: 在项目根目录创建 .env.production
4. 打包前: 确保配置文件存在且配置正确
5. 验证: 打包后检查 API 请求 URL 是否正确