15 KiB
15 KiB
2.6 环境变量配置
:::tip 概述
项目使用 .env 文件管理环境变量，支持开发、测试、生产等多环境切换。配置优先级：真实环境变量 > .env > config/*.php 中的默认值。模板文件为 .env.example，首次部署复制为 .env 后修改。
:::
.env 文件结构
项目 .env 采用 Laravel 标准的 KEY=VALUE 扁平格式（无分组），每个键按前缀对应一个 config/*.php 配置文件，通过 env() 函数读取：
# =============================================================================
# .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.naivevue # 数据库名
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 重要键说明
JWT_SECRET为空或不足 32 字符时，应用拒绝启动（fail-close）。生成：openssl rand -base64 32。DB_PREFIX=laravel_必须保留，漏配会报表不存在。REDIS_PASSWORD与 Redis 实际密码必须一致，否则验证码、登录全部失败。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 目录结构）。
配置项详解
应用配置
| 变量 | 默认值 | 说明 |
|---|---|---|
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 | 模块应用名（影响路由前缀和前端目录） |
多环境配置
开发环境
APP_ENV=local
APP_DEBUG=true # 开启调试模式（异常返回真实消息）
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_DATABASE=rxthinkcmf.laravel13.naivevue
DB_PREFIX=laravel_
CORS_ALLOW_ORIGIN=* # 允许所有来源（Vite 代理/直连均可用）
CAPTCHA_BYPASS_CODE= # 可设置万能验证码（仅 debug 下生效）
生产环境
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/负载均衡后时配置
生成强密钥
# 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));"
配置缓存管理
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 快速体验。
:::
前端环境变量
前端使用 Vite 的环境变量机制，配置文件位于 ui/ 目录（.env、.env.development、.env.production、.env.test）：
.env.development（开发环境）
# 跨域代理（开发环境 /api 请求由此转发到后端）
VITE_PROXY=[["/api","http://admin.laravel13.naivevue/api"]]
# API 接口地址（留空，由 Vite 代理处理）
VITE_GLOB_API_URL =
# 接口前缀
VITE_GLOB_API_URL_PREFIX = /api
# 是否开启mock（false = 使用真实后端 API）
VITE_USE_MOCK = false
.env.production（生产环境）
# API 接口地址（留空，由 Nginx 代理处理）
VITE_GLOB_API_URL =
# 接口前缀
VITE_GLOB_API_URL_PREFIX = /api
在代码中访问环境变量：
// 通过 import.meta.env 访问 Vite 环境变量
// VITE_ 前缀的变量才会被暴露给客户端代码
const apiUrl = import.meta.env.VITE_GLOB_API_URL
详细说明见 9.3 环境与构建配置与 2.4 前端服务启动。