签入版本

This commit is contained in:
2026-10-08 17:50:29 +08:00
parent 809750b47e
commit e213a9b31d
444 changed files with 39366 additions and 37533 deletions
@@ -1,225 +1,262 @@
# 2.5 环境变量配置
# 2.6 环境变量配置
:::tip 概述
项目使用 `.env` 文件管理环境变量,支持开发、测试、生产等多环境切换。配置优先级:`.env` > `config/*.php` > 代码默认值。
项目使用 `.env` 文件管理环境变量,支持开发、测试、生产等多环境切换。配置优先级:**真实环境变量 > `.env` > `config/*.php` 中的默认值**。模板文件为 `.env.example`,首次部署复制为 `.env` 后修改。
:::
## .env 文件结构
项目 `.env` 文件采用 INI 分组格式,每个分组对应一个 `config/*.php` 配置文件:
项目 `.env` 采用 Laravel 标准的 `KEY=VALUE` 扁平格式(无分组),每个键按前缀对应一个 `config/*.php` 配置文件,通过 `env()` 函数读取:
```ini
; =============================================================================
; .env 环境变量配置文件
; =============================================================================
; 格式:INI 分组格式,[分组] 下的键值对通过 env() 函数读取
; 优先级:.env > config/*.php > 代码默认值
; =============================================================================
# =============================================================================
# .env 环境变量配置文件(Laravel 标准格式)
# =============================================================================
# 格式:KEY=VALUE 扁平结构,按前缀映射到 config/*.php(如 JWT_* → config/jwt.php)
# 优先级:真实环境变量 > .env > config/*.php 默认值
# 修改后执行 php artisan config:clear 清除配置缓存
# =============================================================================
; 全局开关(不属于任何分组)
APP_DEBUG = true ; 调试模式(开发 true,生产 false)
# ─── 应用基础 ─────────────────────────────────────────────
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 一致)
[APP]
DEFAULT_TIMEZONE = Asia/Shanghai ; 默认时区
DEMO = false ; 演示模式(true=拦截所有写操作)
SHOW_ERROR_MSG = true ; 显示错误详情(生产环境设为 false)
# ─── 日志 ─────────────────────────────────────────────────
LOG_CHANNEL=stack # 日志通道
LOG_LEVEL=debug # 日志级别(生产改为 info)
[DATABASE]
TYPE = mysql ; 数据库类型(mysql / pgsql / sqlsrv / oracle / sqlite)
HOSTNAME = 127.0.0.1 ; 数据库服务器地址
DATABASE = rxthinkcmf.thinkphp6.elevue ; 数据库名
USERNAME = root ; 用户名
PASSWORD = root ; 密码
HOSTPORT = 3306 ; 端口
CHARSET = utf8mb4 ; 字符集(支持 emoji)
DEBUG = true ; SQL 调试(显示执行的 SQL 语句)
PREFIX = think_ ; 表前缀
# ─── 数据库 ───────────────────────────────────────────────
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_ 前缀,必须保留)
[JWT]
SECRET = rxthinkcmf_jwt_secret_key_2024 ; 签名密钥(生产环境务必修改)
ACCESS_TTL = 7200 ; access_token 有效期(秒),默认 2 小时
REFRESH_TTL = 604800 ; refresh_token 有效期(秒),默认 7 天
ISSUER = rxthinkcmf ; 签发者标识
# ─── 会话 / 缓存 / 队列(统一走 Redis,必需)──────────────
SESSION_DRIVER=redis # 会话驱动
SESSION_LIFETIME=120 # 会话有效期(分钟)
QUEUE_CONNECTION=redis # 队列驱动
CACHE_STORE=redis # 缓存驱动
[FILE]
UPLOAD_DIR = D:/uploads/rxthinkcmf ; 上传根目录(绝对路径)
DOMAIN_URL = http://file.thinkphp6.elevue ; 文件访问域名
IMAGE_EXT = gif,jpg,jpeg,png,bmp,webp,svg ; 允许的图片后缀
FILE_EXT = gif,jpg,jpeg,png,bmp,webp,svg,doc,docx,xls,xlsx,ppt,pptx,pdf,zip,rar,txt,csv,mp3,mp4,sql,js,css ; 允许的文件后缀
MAX_SIZE = 10 ; 单文件最大大小(MB)
# ─── Redis ────────────────────────────────────────────────
REDIS_CLIENT=phpredis # 客户端(phpredis 扩展)
REDIS_HOST=127.0.0.1 # Redis 地址
REDIS_PASSWORD=null # Redis 密码(设置了 requirepass 时必须同步)
REDIS_PORT=6379 # Redis 端口
[CACHE]
DRIVER = file ; 缓存驱动(file=文件,redis=Redis)
REDIS_HOST = 127.0.0.1 ; Redis 地址(driver=redis 时生效)
REDIS_PORT = 6379 ; Redis 端口
REDIS_PASSWORD = ; Redis 密码(无密码留空)
REDIS_DB = 0 ; Redis 数据库编号
REDIS_PREFIX = rx: ; 缓存键前缀
# ─── 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 # 签发者标识
[CORS]
ALLOW_ORIGIN = * ; 允许的来源(* = 所有)
# ─── 文件上传 ─────────────────────────────────────────────
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 # 允许的文件后缀
[API]
CAMEL_SNAKE_CONVERT = true ; 驼峰/下划线自动转换
# ─── CORS 跨域 ────────────────────────────────────────────
CORS_ALLOW_ORIGIN=* # 允许来源(逗号分隔;开发 *,生产改为具体域名)
[CAPTCHA]
CAPTCHA_BYPASS_CODE = ; 万能验证码(开发用,生产务必留空)
CAPTCHA_LENGTH = 6 ; 验证码字符长度(4-6位)
CAPTCHA_EXPIRE = 300 ; 验证码过期时间(秒)
# ─── API ──────────────────────────────────────────────────
API_CAMEL_SNAKE_CONVERT=true # 请求/响应键名驼峰与下划线自动转换
[LANG]
default_lang = zh-cn ; 默认语言
# ─── 多租户 ───────────────────────────────────────────────
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]`
### 应用配置
| 变量 | 默认值 | 说明 |
|------|--------|------|
| `DEFAULT_TIMEZONE` | `Asia/Shanghai` | 默认时区 |
| `DEMO` | `false` | 演示模式,开启后拦截所有写操作 |
| `SHOW_ERROR_MSG` | `true` | 是否显示错误详情,生产环境设为 `false` |
| `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 用 |
全局变量(不属于任何分组):
### 数据库配置
| 变量 | 默认值 | 说明 |
|------|--------|------|
| `APP_DEBUG` | `true` | 调试模式,生产环境设为 `false` |
| `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_ | 表前缀 |
### 数据库配置 `[DATABASE]`
### JWT 配置
| 变量 | 默认值 | 说明 |
|------|--------|------|
| `TYPE` | `mysql` | 数据库类型:mysql / pgsql / sqlsrv / oracle / sqlite |
| `HOSTNAME` | `127.0.0.1` | 数据库主机 |
| `DATABASE` | - | 数据库名称(SQLite 为文件路径) |
| `USERNAME` | `root` | 数据库用户名 |
| `PASSWORD` | - | 数据库密码 |
| `HOSTPORT` | `3306` | 数据库端口 |
| `CHARSET` | `utf8mb4` | 字符集 |
| `DEBUG` | `true` | 是否开启 SQL 调试 |
| `PREFIX` | `think_` | 表前缀 |
| `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 | 签发者标识 |
### JWT 配置 `[JWT]`
### Redis / 缓存配置
| 变量 | 默认值 | 说明 |
|------|--------|------|
| `SECRET` | 内置默认值 | 签名密钥,**生产环境务必修改** |
| `ACCESS_TTL` | `7200` | access_token 有效期(秒),默认 2 小时 |
| `REFRESH_TTL` | `604800` | refresh_token 有效期(秒),默认 7 天 |
| `ISSUER` | `rxthinkcmf` | 签发者标识 |
| `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 | 队列驱动 |
### 文件上传配置 `[FILE]`
:::warning
会话 / 缓存 / 队列驱动**不要改回 `database`**——数据库脚本不含 Laravel framework 表(`sessions` / `cache` / `jobs`),改回后登录与缓存会直接报表不存在。
:::
### 文件上传配置
| 变量 | 默认值 | 说明 |
|------|--------|------|
| `UPLOAD_DIR` | - | 上传根目录(绝对路径) |
| `DOMAIN_URL` | - | 文件访问域名 |
| `IMAGE_EXT` | `gif,jpg,jpeg,png,bmp,webp,svg` | 允许的图片后缀 |
| `FILE_UPLOAD_DIR` | uploads | 上传根目录(相对 `public/`) |
| `FILE_DOMAIN_URL` | (空) | 文件访问域名前缀,空则返回相对路径 |
| `FILE_MAX_SIZE` | 10 | 单文件大小上限(MB) |
| `FILE_IMAGE_EXT` | gif,jpg,... | 允许的图片后缀(**svg 已移除**:内嵌 JS 导致 XSS 风险) |
| `FILE_EXT` | 多种后缀 | 允许的文件后缀 |
| `MAX_SIZE` | `10` | 单文件最大大小(MB) |
### 缓存配置 `[CACHE]`
### CORS / API 配置
| 变量 | 默认值 | 说明 |
|------|--------|------|
| `DRIVER` | `file` | 缓存驱动:`file` 或 `redis` |
| `REDIS_HOST` | `127.0.0.1` | Redis 主机(driver=redis 时生效) |
| `REDIS_PORT` | `6379` | Redis 端口(driver=redis 时生效) |
| `REDIS_PASSWORD` | - | Redis 密码 |
| `REDIS_DB` | `0` | Redis 数据库编号 |
| `REDIS_PREFIX` | `rx:` | 缓存键前缀 |
| `CORS_ALLOW_ORIGIN` | * | 允许来源,逗号分隔;凭证模式下会回显具体 Origin |
| `API_CAMEL_SNAKE_CONVERT` | true | 请求/响应键名驼峰与下划线自动转换 |
### CORS 配置 `[CORS]`
### 验证码配置
| 变量 | 默认值 | 说明 |
|------|--------|------|
| `ALLOW_ORIGIN` | `*` | 允许的来源,`*` 表示所有 |
| `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 | 噪点数量 |
### API 配置 `[API]`
### 代码生成器配置
| 变量 | 默认值 | 说明 |
|------|--------|------|
| `CAMEL_SNAKE_CONVERT` | `true` | 驼峰/下划线自动转换开关 |
### 验证码配置 `[CAPTCHA]`
| 变量 | 默认值 | 说明 |
|------|--------|------|
| `CAPTCHA_BYPASS_CODE` | (空) | 万能验证码,跳过验证。仅用于开发调试,**生产环境务必留空** |
| `CAPTCHA_LENGTH` | `6` | 验证码字符长度(4-6位) |
| `CAPTCHA_EXPIRE` | `300` | 验证码过期时间(秒),默认 5 分钟 |
| `CAPTCHA_RATE_WINDOW` | `60` | 防刷窗口期(秒) |
| `CAPTCHA_RATE_LIMIT` | `20` | 窗口期内最大获取次数 |
| `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` | `8` | 干扰线数量 |
| `CAPTCHA_NOISE_DOTS` | `500` | 噪点数量 |
### 国际化配置 `[LANG]`
| 变量 | 默认值 | 说明 |
|------|--------|------|
| `default_lang` | `zh-cn` | 默认语言 |
### 代码生成器配置 `[GENERATOR]`
| 变量 | 默认值 | 说明 |
|------|--------|------|
| `PARENT_MENU_ID` | `189` | 生成模块的父菜单ID |
| `APP_NAME` | `tool` | 模块应用名(影响路由前缀和前端目录) |
| `GENERATOR_PARENT_MENU_ID` | 189 | 生成模块挂载的父菜单 ID |
| `GENERATOR_APP_NAME` | tool | 模块应用名(影响路由前缀和前端目录) |
## 多环境配置
### 开发环境
```ini
; 开发环境配置(调试开启,使用文件缓存)
APP_DEBUG = true ; 开启调试模式
APP_ENV=local
APP_DEBUG=true # 开启调试模式(异常返回真实消息)
[APP]
SHOW_ERROR_MSG = true ; 显示错误详情
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_DATABASE=rxthinkcmf.laravel13.elevue
DB_PREFIX=laravel_
[DATABASE]
DEBUG = true ; 显示执行的 SQL
CORS_ALLOW_ORIGIN=* # 允许所有来源(Vite 代理/直连均可用)
[CACHE]
DRIVER = file ; 使用文件缓存(无需 Redis)
CAPTCHA_BYPASS_CODE= # 可设置万能验证码(仅 debug 下生效)
```
### 生产环境
```ini
; 生产环境配置(调试关闭,使用 Redis 缓存)
APP_DEBUG = false ; 关闭调试模式
APP_ENV=production
APP_DEBUG=false # 关闭调试模式(防止堆栈泄露)
[APP]
SHOW_ERROR_MSG = false ; 不显示错误详情(防止泄露)
DB_PASSWORD=<强密码>
[DATABASE]
DEBUG = false ; 不显示 SQL
JWT_SECRET=<openssl rand -base64 32 生成的随机值> # 必须修改
[CACHE]
DRIVER = redis ; 使用 Redis 缓存
REDIS_HOST = 127.0.0.1 ; Redis 地址
REDIS_PORT = 6379 ; Redis 端口
REDIS_PASSWORD = <你的Redis密码> ; Redis 密码
CORS_ALLOW_ORIGIN=https://admin.example.com # 限制为实际域名
[JWT]
SECRET = <随机生成的强密钥> ; 签名密钥(必须修改)
[CORS]
ALLOW_ORIGIN = https://admin.example.com ; 限制为实际域名
CAPTCHA_BYPASS_CODE= # 必须留空
DEMO_MODE=false # 按需开启演示模式
TRUSTED_PROXIES= # 部署在 CDN/负载均衡后时配置
```
### 生成强密钥
```bash
# Linux / macOS:使用 OpenSSL 生成 32 字节随机 Base64 字符串
# Linux / macOS / Windows(Git Bash):OpenSSL 生成 32 字节随机 Base64 字符串
openssl rand -base64 32
# PHP:生成 32 字节随机十六进制字符串(64 个字符)
@@ -228,9 +265,21 @@ openssl rand -base64 32
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 的环境变量机制,配置文件位于 `ui/` 目录:
前端使用 Vite 的环境变量机制,配置文件位于前端仓库目录:
### `.env.development`(开发环境)
@@ -262,3 +311,5 @@ VITE_GLOB_API_URL_PREFIX=
// VITE_ 前缀的变量才会被暴露给客户端代码
const apiUrl = import.meta.env.VITE_GLOB_API_URL
```
详细说明见 [2.4 前端服务启动](/zh/quickstart/frontend-start.html)。