开发指南

环境变量

租户前端使用三层环境变量配置：

.env（通用，所有环境生效）

.env.development（开发环境）

.env.production（生产环境）

重要：生产构建时 VITE_API_URL 必须填写后端的完整域名（含协议），因为 Vite 代理仅在开发环境生效。

Vite 代理配置

vite.config.ts 中为以下路径配置了开发代理：

proxy: {
  '/tenant': {
    target: VITE_API_PROXY_URL,  // http://localhost:4096
    changeOrigin: true,
    bypass(req) {
      // 避免代理 Vite 内部请求和静态资源
      if (req.headers.accept?.includes('text/html')) return req.url
      const pathname = (req.url || '').split('?')[0]
      if (pathname.includes('/@') || pathname.includes('/node_modules/') ||
          pathname.includes('__vite') || /\.\w+$/.test(pathname)) {
        return req.url
      }
    }
  },
  '/attachment': { target: VITE_API_PROXY_URL, changeOrigin: true },
  '/captcha':    { target: VITE_API_PROXY_URL, changeOrigin: true },
  '/site':       { target: VITE_API_PROXY_URL, changeOrigin: true },
  '/system':     { target: VITE_API_PROXY_URL, changeOrigin: true },
}

/tenant 代理的 bypass 逻辑

由于前端路由前缀也是 /tenant，Vite 开发服务器需要区分：

• API 请求（/tenant/auth/login）→ 代理到后端
• 前端页面（/tenant/login，Accept 含 text/html）→ 返回前端
• 静态资源（/@vite/client、.js 文件等）→ 返回前端

bypass 函数通过检查 Accept 头、路径前缀和文件扩展名来实现这一区分。

本地联调步骤

1. 启动后端

cd server
gf run main.go
# 默认运行在 http://localhost:4096（取决于 config.yaml 配置）

2. 确认代理目标

检查 .env.development 中 VITE_API_PROXY_URL 是否指向后端地址：

VITE_API_PROXY_URL = http://localhost:4096

3. 启动租户前端

cd web-tenant
pnpm install
pnpm dev
# 访问 http://localhost:3007/tenant/login

4. 登录测试

使用租户管理员账号登录。租户管理员数据存储在 xy_tenant_admin 表，与平台管理员 xy_admin_user 独立。

常见问题

Q: 开发时 API 请求 404

1. 确认后端服务已启动
2. 确认 VITE_API_PROXY_URL 端口正确
3. 确认后端 cmd.go 中租户路由已注册

Q: 生产环境图片不显示

Nginx 缺少 /attachment/ 代理规则。所有附件 URL 形如 /attachment/xxx，必须反向代理到后端。

Q: 生产环境 API 请求到前端域名

检查 .env.production 中 VITE_API_URL 是否设置为后端完整域名（含 https://）。

Q: 验证码不显示

Nginx 缺少 /captcha/ 代理规则，或 .env.development 代理配置遗漏。

Q: /tenant 路径下的页面刷新后空白

项目使用 Hash 路由模式（URL 带 #），正常情况不会出现此问题。如果确实空白，检查 VITE_BASE_URL 配置是否与部署路径一致。