spring-ai-alibaba-studio/agent-chat-ui/ENV_CONFIG.md
项目现在使用多个环境文件来自动适配不同的运行模式：
| 文件名 | 用途 | 何时使用 | Git 状态 |
|---|---|---|---|
.env.example | 示例配置 | 参考模板 | ✅ 提交到Git |
.env.local | 通用配置 | 所有模式的备用 | ❌ 不提交 |
.env.development.local | 开发配置 | pnpm dev | ❌ 不提交 |
.env.production.local | 生产配置 | pnpm build:static | ❌ 不提交 |
Next.js 会按以下顺序加载环境变量（后者覆盖前者）：
.env # 所有环境的默认值
.env.local # 本地覆盖，所有环境
.env.development # 开发环境
.env.development.local # 开发环境本地覆盖 (优先级最高)
.env.production # 生产环境
.env.production.local # 生产环境本地覆盖 (优先级最高)
.env.development.local (开发模式)# 开发模式下连接到独立的Spring Boot后端
NEXT_PUBLIC_API_URL=http://localhost:8080
NEXT_PUBLIC_APP_NAME=research_agent
NEXT_PUBLIC_USER_ID=user-001
效果：
pnpm dev 时自动使用http://localhost:3000http://localhost:8080/apps/....env.production.local (生产模式)# 生产模式下使用相对路径
# 不设置 NEXT_PUBLIC_API_URL
NEXT_PUBLIC_APP_NAME=research_agent
NEXT_PUBLIC_USER_ID=user-001
效果：
pnpm build:static 时自动使用.env.local (备用配置)# 通用配置，会被上面两个文件覆盖
NEXT_PUBLIC_APP_NAME=research_agent
NEXT_PUBLIC_USER_ID=user-001
# 1. 确保后端运行在 localhost:8080
# 2. 启动前端开发服务器
pnpm dev
# 3. 访问 http://localhost:3000
# 4. API 自动请求到 http://localhost:8080
使用的环境文件: .env.development.local
API URL: http://localhost:8080 ✅
# 1. 构建静态文件
pnpm deploy
# 2. 启动 Spring Boot (端口 9090)
# 3. 访问 http://localhost:9090/chatui/
# 4. API 自动请求到 http://localhost:9090
使用的环境文件: .env.production.local
API URL: '' (空字符串，使用相对路径) ✅
pnpm build
pnpm start
使用的环境文件: .env.production.local
API URL: '' (空字符串)
编辑 .env.development.local:
# 如果后端运行在不同的端口
NEXT_PUBLIC_API_URL=http://localhost:9090
# 或使用远程服务器
NEXT_PUBLIC_API_URL=https://dev-server.example.com
编辑任一环境文件：
NEXT_PUBLIC_APP_NAME=my_custom_agent
NEXT_PUBLIC_USER_ID=user-123
NEXT_PUBLIC_API_URL'' (空字符串)http://localhost:8080NEXT_PUBLIC_APP_NAMEresearch_agentNEXT_PUBLIC_USER_IDuser-001不同环境使用不同文件
.env.development.local.env.production.local不要提交 .local 文件到 Git
使用 .env.example 作为模板
不要在 .env.local 中设置 NEXT_PUBLIC_API_URL
不要在代码中硬编码配置
检查:
# 查看当前环境变量
cat .env.development.local
# 确认包含：
NEXT_PUBLIC_API_URL=http://localhost:8080
解决:
# 如果文件不存在，从示例复制
cp .env.example .env.development.local
# 然后编辑文件，确保 NEXT_PUBLIC_API_URL 正确
检查:
# 查看生产环境配置
cat .env.production.local
# 确认 NEXT_PUBLIC_API_URL 被注释或不存在
解决:
# 编辑 .env.production.local，注释掉或删除 API_URL
# NEXT_PUBLIC_API_URL=http://localhost:8080 # ❌ 删除这行
# 重新构建
pnpm deploy
调试方法:
在代码中临时添加日志（例如 src/lib/spring-ai-api.ts）：
export function createApiClient(): SpringAIApiClient {
const baseUrl = process.env.NEXT_PUBLIC_API_URL || '';
console.log('🔍 API Base URL:', baseUrl);
console.log('🔍 Environment:', process.env.NODE_ENV);
return new SpringAIApiClient(baseUrl);
}
然后查看浏览器控制台输出。