111 lines
3.2 KiB
Markdown
111 lines
3.2 KiB
Markdown
# 环境变量配置说明
|
||
|
||
本项目使用 Vite 的环境变量系统来管理不同环境的配置。
|
||
|
||
## 环境变量文件
|
||
|
||
### `.env`
|
||
默认环境变量文件，所有环境都会加载。通常包含本地开发的默认配置。
|
||
|
||
### `.env.development`
|
||
开发环境配置，运行 `pnpm dev` 时会自动加载。
|
||
|
||
### `.env.production`
|
||
生产环境配置，运行 `pnpm build` 时会自动加载。
|
||
|
||
### `.env.local`
|
||
本地环境变量文件（**不会被 git 跟踪**），用于覆盖默认配置。
|
||
- 复制 `.env.local.example` 为 `.env.local` 并根据需要修改
|
||
- 此文件优先级最高，会覆盖其他环境变量文件中的同名变量
|
||
|
||
## 环境变量列表
|
||
|
||
| 变量名 | 说明 | 默认值 | 示例 |
|
||
|--------|------|--------|------|
|
||
| `VITE_PORT` | 开发服务器端口 | `5173` | `5173` |
|
||
| `VITE_API_BASE_URL` | API 基础地址 | `http://localhost:3200/api` | `https://api.example.com/api` |
|
||
| `VITE_APP_NAME` | 应用名称 | `投小记` | `投小记` |
|
||
| `VITE_APP_TITLE` | 应用标题 | `投小记 - 投资决策与复盘工具` | - |
|
||
| `VITE_ENV` | 环境标识 | `development` | `production` |
|
||
| `VITE_USE_MOCK` | 是否启用 Mock 数据 | `false` | `true` |
|
||
| `VITE_DEBUG` | 是否显示调试信息 | `true` (开发) / `false` (生产) | `true` |
|
||
|
||
## 使用方法
|
||
|
||
### 1. 在代码中使用环境变量
|
||
|
||
```typescript
|
||
// 方式1：使用配置对象（推荐）
|
||
import { envConfig } from '@/config/env'
|
||
|
||
const apiUrl = envConfig.apiBaseUrl
|
||
const appName = envConfig.appName
|
||
|
||
// 方式2：直接使用 import.meta.env（不推荐，缺少类型提示）
|
||
const apiUrl = import.meta.env.VITE_API_BASE_URL
|
||
```
|
||
|
||
### 2. 在 API 服务中使用
|
||
|
||
```typescript
|
||
import { api } from '@/services/api'
|
||
|
||
// 使用配置好的 API 客户端
|
||
const data = await api.get('/users')
|
||
```
|
||
|
||
### 3. 修改环境变量
|
||
|
||
#### 开发环境
|
||
编辑 `.env.development` 文件
|
||
|
||
#### 生产环境
|
||
编辑 `.env.production` 文件，或在部署平台设置环境变量
|
||
|
||
#### 本地个性化配置
|
||
1. 复制 `.env.local.example` 为 `.env.local`
|
||
2. 在 `.env.local` 中修改需要的变量
|
||
|
||
## 注意事项
|
||
|
||
1. **变量命名**：所有需要在客户端代码中使用的环境变量必须以 `VITE_` 开头
|
||
2. **类型安全**：使用 `src/config/env.ts` 中的 `envConfig` 对象可以获得类型提示
|
||
3. **敏感信息**：不要在环境变量文件中存储敏感信息（如密钥、密码），这些应该通过后端 API 获取
|
||
4. **Git 跟踪**：
|
||
- `.env`、`.env.development`、`.env.production` 会被 git 跟踪
|
||
- `.env.local`、`.env*.local` 不会被 git 跟踪（已在 .gitignore 中配置）
|
||
|
||
## 部署说明
|
||
|
||
### 开发环境
|
||
```bash
|
||
pnpm dev
|
||
# 会自动加载 .env 和 .env.development
|
||
```
|
||
|
||
### 生产环境
|
||
```bash
|
||
pnpm build
|
||
# 会自动加载 .env 和 .env.production
|
||
```
|
||
|
||
### 预览构建结果
|
||
```bash
|
||
pnpm preview
|
||
# 会使用生产环境配置预览构建结果
|
||
```
|
||
|
||
## 常见问题
|
||
|
||
### Q: 如何修改 API 地址？
|
||
A: 修改对应环境的 `.env` 文件中的 `VITE_API_BASE_URL` 变量
|
||
|
||
### Q: 如何在不同端口运行？
|
||
A: 修改 `.env.development` 中的 `VITE_PORT` 变量，或使用命令行参数：
|
||
```bash
|
||
VITE_PORT=3000 pnpm dev
|
||
```
|
||
|
||
### Q: 环境变量修改后不生效？
|
||
A: 重启开发服务器，环境变量只在启动时加载
|