316 lines
15 KiB
Markdown
316 lines
15 KiB
Markdown
# 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/app.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)。
|