# 2.6 环境变量配置

:::tip 概述
项目使用 `.env` 文件管理环境变量，支持开发、测试、生产等多环境切换。配置优先级：**真实环境变量 > `.env` > `config/*.php` 中的默认值**。模板文件为 `.env.example`，首次部署复制为 `.env` 后修改。
:::

## .env 文件结构

项目 `.env` 采用 Laravel 标准的 `KEY=VALUE` 扁平格式（无分组），每个键按前缀对应一个 `config/*.php` 配置文件，通过 `env()` 函数读取：

```ini
# =============================================================================
# .env 环境变量配置文件（Laravel 标准格式）
# =============================================================================
# 格式：KEY=VALUE 扁平结构，按前缀映射到 config/*.php（如 JWT_* → config/jwt.php）
# 优先级：真实环境变量 > .env > config/*.php 默认值
# 修改后执行 php artisan config:clear 清除配置缓存
# =============================================================================

# ─── 应用基础 ─────────────────────────────────────────────
APP_NAME=Laravel                       # 应用名称
APP_ENV=local                          # 环境标识（local / production）
APP_KEY=                               # 应用加密密钥（php artisan key:generate 生成）
APP_DEBUG=true                         # 调试模式（开发 true，生产必须 false）
APP_URL=http://localhost               # 应用访问地址
APP_TIMEZONE=Asia/Shanghai             # 应用时区（写入时间字段用，需与 MySQL、PHP 一致）
APP_LOCALE=en                          # 默认语言
BCRYPT_ROUNDS=12                       # bcrypt 成本因子（与 PasswordService 一致）

# ─── 日志 ─────────────────────────────────────────────────
LOG_CHANNEL=stack                      # 日志通道
LOG_LEVEL=debug                        # 日志级别（生产改为 info）

# ─── 数据库 ───────────────────────────────────────────────
DB_CONNECTION=mysql                     # 数据库类型（mysql / pgsql / sqlsrv / sqlite）
DB_HOST=127.0.0.1                      # 数据库地址
DB_PORT=3306                           # 端口
DB_DATABASE=rxthinkcmf.laravel13.elevue # 数据库名
DB_USERNAME=root                       # 用户名
DB_PASSWORD=root                       # 密码
DB_PREFIX=laravel_                     # 表前缀（脚本使用 laravel_ 前缀，必须保留）

# ─── 会话 / 缓存 / 队列（统一走 Redis，必需）──────────────
SESSION_DRIVER=redis                   # 会话驱动
SESSION_LIFETIME=120                   # 会话有效期（分钟）
QUEUE_CONNECTION=redis                 # 队列驱动
CACHE_STORE=redis                      # 缓存驱动

# ─── Redis ────────────────────────────────────────────────
REDIS_CLIENT=phpredis                  # 客户端（phpredis 扩展）
REDIS_HOST=127.0.0.1                   # Redis 地址
REDIS_PASSWORD=null                    # Redis 密码（设置了 requirepass 时必须同步）
REDIS_PORT=6379                        # Redis 端口

# ─── JWT ──────────────────────────────────────────────────
JWT_SECRET=                            # 签名密钥（必须 >= 32 字符，启动 fail-close 校验）
JWT_ACCESS_TTL=7200                    # access_token 有效期（秒），默认 2 小时
JWT_REFRESH_TTL=604800                 # refresh_token 有效期（秒），默认 7 天
JWT_PERMS_TTL=7200                     # 权限缓存 TTL（秒），建议不小于 refresh_ttl
JWT_ISSUER=rxthinkcmf                  # 签发者标识

# ─── 文件上传 ─────────────────────────────────────────────
FILE_UPLOAD_DIR=uploads                # 上传根目录（相对 public/）
FILE_DOMAIN_URL=                       # 文件访问域名（空则返回相对路径）
FILE_MAX_SIZE=10                       # 单文件大小上限（MB）
FILE_IMAGE_EXT=gif,jpg,jpeg,png,bmp,webp          # 允许的图片后缀（svg 已移除：XSS 风险）
FILE_EXT=gif,jpg,jpeg,png,bmp,webp,doc,docx,xls,xlsx,ppt,pptx,pdf,zip,rar,txt,csv  # 允许的文件后缀

# ─── CORS 跨域 ────────────────────────────────────────────
CORS_ALLOW_ORIGIN=*                    # 允许来源（逗号分隔；开发 *，生产改为具体域名）

# ─── API ──────────────────────────────────────────────────
API_CAMEL_SNAKE_CONVERT=true           # 请求/响应键名驼峰与下划线自动转换

# ─── 多租户 ───────────────────────────────────────────────
DEFAULT_TENANT_ID=1                    # 平台用户新增数据时的默认租户 ID

# ─── 演示模式 ─────────────────────────────────────────────
DEMO_MODE=false                        # true=拦截写操作（POST/PUT/DELETE/PATCH），#[DemoAllow] 例外

# ─── 受信代理 ─────────────────────────────────────────────
TRUSTED_PROXIES=                       # 逗号分隔的代理 IP 或 CIDR（CDN/负载均衡场景）

# ─── 验证码 ───────────────────────────────────────────────
CAPTCHA_LENGTH=6                       # 字符长度
CAPTCHA_CHARS=ABCDEFGHJKLMNPQRSTUVWXYZ2346789  # 字符集（已排除 0O、1lI 易混淆字符）
CAPTCHA_EXPIRE=300                     # 有效期（秒）
CAPTCHA_RATE_WINDOW=60                 # 防刷窗口期（秒）
CAPTCHA_RATE_LIMIT=10                  # 窗口期内最大获取次数
CAPTCHA_BYPASS_CODE=                   # 万能验证码（仅 APP_DEBUG=true 生效，生产务必留空）

# ─── 代码生成器 ───────────────────────────────────────────
GENERATOR_PARENT_MENU_ID=189           # 生成模块的父菜单 ID
GENERATOR_APP_NAME=tool                # 应用名（路由前缀、前端目录）
```

:::danger 重要键说明
1. `JWT_SECRET` 为空或不足 32 字符时，应用**拒绝启动**（fail-close）。生成：`openssl rand -base64 32`。
2. `DB_PREFIX=laravel_` 必须保留，漏配会报表不存在。
3. `REDIS_PASSWORD` 与 Redis 实际密码必须一致，否则验证码、登录全部失败。
4. `APP_DEBUG` 生产环境必须为 `false`（否则异常堆栈泄露给前端）。
:::

## 配置文件映射

| .env 键前缀 | 配置文件 | 说明 |
|-------------|----------|------|
| `APP_*` | `config/app.php` | 应用名称 / 环境 / 调试 / 密钥 |
| `DB_*` | `config/database.php` | 数据库连接 + Redis 连接 |
| `SESSION_*` | `config/session.php` | 会话 |
| `CACHE_*` / `QUEUE_*` | `config/cache.php` / `config/queue.php` | 缓存 / 队列 |
| `JWT_*` | `config/jwt.php` ★ | JWT 密钥与有效期 |
| `FILE_*` | `config/file.php` ★ | 文件上传 |
| `CORS_ALLOW_ORIGIN` | `config/cors.php` ★ | 跨域 |
| `API_*` | `config/api.php` ★ | 驼峰转换开关 |
| `CAPTCHA_*` | `config/captcha.php` ★ | 验证码 |
| `DEFAULT_TENANT_ID` | `config/tenant.php` ★ | 多租户 |
| `GENERATOR_*` | `config/generator.php` | 代码生成器 |
| `TRUSTED_PROXIES` | `config/middleware.php` ★ | 受信代理 |
| `LOG_*` | `config/logging.php` | 日志 |
| `MAIL_*` | `config/mail.php` | 邮件 |

标 ★ 为本项目独立维护的配置文件（见 [1.3 目录结构](/zh/directory.html)）。

## 配置项详解

### 应用配置

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `APP_NAME` | Laravel | 应用名称 |
| `APP_ENV` | local | 环境标识 |
| `APP_KEY` | （空） | 应用加密密钥，`key:generate` 生成 |
| `APP_DEBUG` | true | 调试模式，**生产必须 false** |
| `APP_URL` | http://localhost | 应用访问地址 |
| `APP_TIMEZONE` | Asia/Shanghai | 应用时区，`create_time` / `update_time` 等时间字段按此写入，需与 MySQL、PHP 时区一致 |
| `BCRYPT_ROUNDS` | 12 | 密码哈希成本因子 |
| `DEMO_MODE` | false | 演示模式，开启后拦截所有写操作 |
| `DEFAULT_TENANT_ID` | 1 | 平台用户新增数据的默认租户 ID |
| `TRUSTED_PROXIES` | （空） | 受信代理 IP/CIDR，CDN 后取真实 IP 用 |

### 数据库配置

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `DB_CONNECTION` | sqlite | 数据库类型：mysql / pgsql / sqlsrv / sqlite |
| `DB_HOST` | 127.0.0.1 | 数据库主机 |
| `DB_PORT` | 3306 | 数据库端口 |
| `DB_DATABASE` | - | 数据库名（SQLite 为文件路径） |
| `DB_USERNAME` | root | 用户名 |
| `DB_PASSWORD` | - | 密码 |
| `DB_PREFIX` | laravel_ | 表前缀 |

### JWT 配置

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `JWT_SECRET` | （必填） | 签名密钥，**>= 32 字符，否则拒绝启动** |
| `JWT_ACCESS_TTL` | 7200 | access_token 有效期（秒），默认 2 小时 |
| `JWT_REFRESH_TTL` | 604800 | refresh_token 有效期（秒），默认 7 天 |
| `JWT_PERMS_TTL` | 7200 | 权限缓存 TTL（秒） |
| `JWT_ISSUER` | rxthinkcmf | 签发者标识 |

### Redis / 缓存配置

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `REDIS_CLIENT` | phpredis | 客户端（需 PHP redis 扩展） |
| `REDIS_HOST` | 127.0.0.1 | Redis 主机 |
| `REDIS_PASSWORD` | null | Redis 密码（无密码保持 null） |
| `REDIS_PORT` | 6379 | Redis 端口 |
| `SESSION_DRIVER` | redis | 会话驱动 |
| `CACHE_STORE` | redis | 缓存驱动 |
| `QUEUE_CONNECTION` | redis | 队列驱动 |

:::warning
会话 / 缓存 / 队列驱动**不要改回 `database`**——数据库脚本不含 Laravel framework 表（`sessions` / `cache` / `jobs`），改回后登录与缓存会直接报表不存在。
:::

### 文件上传配置

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `FILE_UPLOAD_DIR` | uploads | 上传根目录（相对 `public/`） |
| `FILE_DOMAIN_URL` | （空） | 文件访问域名前缀，空则返回相对路径 |
| `FILE_MAX_SIZE` | 10 | 单文件大小上限（MB） |
| `FILE_IMAGE_EXT` | gif,jpg,... | 允许的图片后缀（**svg 已移除**：内嵌 JS 导致 XSS 风险） |
| `FILE_EXT` | 多种后缀 | 允许的文件后缀 |

### CORS / API 配置

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `CORS_ALLOW_ORIGIN` | * | 允许来源，逗号分隔；凭证模式下会回显具体 Origin |
| `API_CAMEL_SNAKE_CONVERT` | true | 请求/响应键名驼峰与下划线自动转换 |

### 验证码配置

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `CAPTCHA_BYPASS_CODE` | （空） | 万能验证码，**仅 APP_DEBUG=true 时生效，生产务必留空** |
| `CAPTCHA_LENGTH` | 6 | 验证码字符长度（4-6 位） |
| `CAPTCHA_EXPIRE` | 300 | 验证码过期时间（秒），默认 5 分钟 |
| `CAPTCHA_RATE_WINDOW` | 60 | 防刷窗口期（秒） |
| `CAPTCHA_RATE_LIMIT` | 10 | 窗口期内最大获取次数 |
| `CAPTCHA_CHARS` | ABCDEFGHJKLMNPQRSTUVWXYZ2346789 | 字符集（已排除 0O、1lI 等易混淆字符） |
| `CAPTCHA_FONT_PATH` | static/fonts/Vera.ttf | 字体路径 |
| `CAPTCHA_IMAGE_WIDTH` | 160 | 图片宽度（像素） |
| `CAPTCHA_IMAGE_HEIGHT` | 50 | 图片高度（像素） |
| `CAPTCHA_FONT_SIZE` | 28 | 字体大小 |
| `CAPTCHA_NOISE_LINES` | 6 | 干扰线数量 |
| `CAPTCHA_NOISE_DOTS` | 300 | 噪点数量 |

### 代码生成器配置

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `GENERATOR_PARENT_MENU_ID` | 189 | 生成模块挂载的父菜单 ID |
| `GENERATOR_APP_NAME` | tool | 模块应用名（影响路由前缀和前端目录） |

## 多环境配置

### 开发环境

```ini
APP_ENV=local
APP_DEBUG=true                         # 开启调试模式（异常返回真实消息）

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_DATABASE=rxthinkcmf.laravel13.elevue
DB_PREFIX=laravel_

CORS_ALLOW_ORIGIN=*                    # 允许所有来源（Vite 代理/直连均可用）

CAPTCHA_BYPASS_CODE=                   # 可设置万能验证码（仅 debug 下生效）
```

### 生产环境

```ini
APP_ENV=production
APP_DEBUG=false                        # 关闭调试模式（防止堆栈泄露）

DB_PASSWORD=<强密码>

JWT_SECRET=<openssl rand -base64 32 生成的随机值>   # 必须修改

CORS_ALLOW_ORIGIN=https://admin.example.com        # 限制为实际域名

CAPTCHA_BYPASS_CODE=                   # 必须留空
DEMO_MODE=false                        # 按需开启演示模式
TRUSTED_PROXIES=                       # 部署在 CDN/负载均衡后时配置
```

### 生成强密钥

```bash
# Linux / macOS / Windows(Git Bash)：OpenSSL 生成 32 字节随机 Base64 字符串
openssl rand -base64 32

# PHP：生成 32 字节随机十六进制字符串（64 个字符）
# random_bytes(32) → 32 字节密码学安全随机数
# bin2hex() → 转为十六进制字符串
php -r "echo bin2hex(random_bytes(32));"
```

## 配置缓存管理

```bash
php artisan config:clear               # 清除配置缓存（修改 .env 后执行）
php artisan config:cache                # 缓存配置（生产环境提升性能）
php artisan config:show jwt.secret      # 查看解析后的配置值（调试用，自动脱敏）
```

:::warning
生产执行 `config:cache` 后，`.env` 的修改**不再生效**，需重新 `config:cache`。Docker 部署通过容器环境变量注入配置（优先级高于 `.env`），见 [2.8 Docker 快速体验](/zh/quickstart/docker.html)。
:::

## 前端环境变量

前端使用 Vite 的环境变量机制，配置文件位于前端仓库目录：

### `.env.development`（开发环境）

```bash
# API 接口基础路径（Vite 代理会将此路径的请求转发到后端）
VITE_GLOB_API_URL=/api

# API 前缀（一般留空）
VITE_GLOB_API_URL_PREFIX=

# 是否启用 Mock 数据（false = 使用真实后端 API）
VITE_USE_MOCK=false
```

### `.env.production`（生产环境）

```bash
# API 接口基础路径（生产环境的实际后端地址）
VITE_GLOB_API_URL=/api

# API 前缀
VITE_GLOB_API_URL_PREFIX=
```

在代码中访问环境变量：

```typescript
// 通过 import.meta.env 访问 Vite 环境变量
// VITE_ 前缀的变量才会被暴露给客户端代码
const apiUrl = import.meta.env.VITE_GLOB_API_URL
```

详细说明见 [2.4 前端服务启动](/zh/quickstart/frontend-start.html)。