easygoadmin/easygoadmin-wiki
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

签入版本

Browse Source
This commit is contained in:
小蚂蚁云
2026-10-25 17:24:27 +08:00
parent 48911cc08f
commit fdbeae092a
1010 changed files with 30682 additions and 95274 deletions
Download Patch File Download Diff File Expand all files Collapse all files
EasyGoAdmin_Gin_NaiveVue/zh/quickstart/env-vars.md
+45 -240
View File
@@ -1,264 +1,69 @@
# 2.5 环境变量配置
# 2.3 配置文件与环境变量
:::tip 概述
项目使用 `.env` 文件管理环境变量，支持开发、测试、生产等多环境切换。配置优先级：`.env` > `config/*.php` > 代码默认值。
配置以 `config/config.yaml` 为基，任意键可被环境变量覆盖（12-Factor 风格）。开发期改 YAML，生产期用环境变量注入敏感项。
:::
## .env 文件结构
## 配置节总览
项目 `.env` 文件采用 INI 分组格式，每个分组对应一个 `config/*.php` 配置文件：
| 配置节 | 职责 |
|---|---|
| server | 监听地址（默认 `:8000`） |
| logger | 日志级别、控制台开关、文件目录 |
| database | GORM 连接（driver/host/port/username/password/dbname/params/连接池） |
| redis | 缓存连接（为空降级内存） |
| jwt | 密钥、签发者、双令牌有效期 |
| captcha | 验证码字符集、尺寸、干扰参数、万能码 |
| rateLimit | 限流开关、窗口、普通/认证接口配额 |
| operationLog | 操作日志总开关与查询类记录开关 |
| job | 日志保留天数、执行锁 TTL |
| tenant | 超管新增租户级数据的默认归属 |
| app | 时区、演示模式 demo、生产模式 prod |
| api | 受信代理、请求体上限、文档/指标端点开关 |
| cors | 允许来源 |
| file | 上传根目录、访问域名、扩展名与大小限制 |
| generator | 生成器开关、菜单挂载父级、覆盖策略 |
| ip2region | 归属地库文件路径 |
```ini
; =============================================================================
; .env 环境变量配置文件
; =============================================================================
; 格式：INI 分组格式，[分组] 下的键值对通过 env() 函数读取
; 优先级：.env > config/*.php > 代码默认值
; =============================================================================
完整键值说明见 [附录 C 配置项速查](/zh/appendix/config-reference.html)。
; 全局开关（不属于任何分组）
APP_DEBUG = true ; 调试模式（开发 true，生产 false）
## 环境变量覆盖规则
[APP]
DEFAULT_TIMEZONE = Asia/Shanghai ; 默认时区
DEMO = false ; 演示模式（true=拦截所有写操作）
SHOW_ERROR_MSG = true ; 显示错误详情（生产环境设为 false）
键名 = **配置路径大写、点换下划线、加 `APP_` 前缀**，仅覆盖 YAML 中已存在的键，空值视为未设置：
[DATABASE]
TYPE = mysql ; 数据库类型（mysql / pgsql / sqlsrv / oracle / sqlite）
HOSTNAME = 127.0.0.1 ; 数据库服务器地址
DATABASE = rxthinkcmf.thinkphp8.elevue ; 数据库名
USERNAME = root ; 用户名
PASSWORD = root ; 密码
HOSTPORT = 3306 ; 端口
CHARSET = utf8mb4 ; 字符集（支持 emoji）
DEBUG = true ; SQL 调试（显示执行的 SQL 语句）
PREFIX = think_ ; 表前缀
[JWT]
SECRET = rxthinkcmf_jwt_secret_key_2024 ; 签名密钥（生产环境务必修改）
ACCESS_TTL = 7200 ; access_token 有效期（秒），默认 2 小时
REFRESH_TTL = 604800 ; refresh_token 有效期（秒），默认 7 天
ISSUER = rxthinkcmf ; 签发者标识
[FILE]
UPLOAD_DIR = D:\xampp8.2\htdocs\RXThinkCMF_ThinkPhp8_EleVue\uploads ; 上传根目录（绝对路径）
DOMAIN_URL = http://file.thinkphp8.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）
[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: ; 缓存键前缀
[CORS]
ALLOW_ORIGIN = * ; 允许的来源（* = 所有）
[API]
CAMEL_SNAKE_CONVERT = true ; 驼峰/下划线自动转换
[CAPTCHA]
CAPTCHA_BYPASS_CODE = ; 万能验证码（开发用，生产务必留空）
CAPTCHA_LENGTH = 6 ; 验证码字符长度（4-6位）
CAPTCHA_EXPIRE = 300 ; 验证码过期时间（秒）
[LANG]
default_lang = zh-cn ; 默认语言
```text
database.default.host → APP_DATABASE_DEFAULT_HOST
redis.default.pass → APP_REDIS_DEFAULT_PASS
jwt.secret → APP_JWT_SECRET
app.prod → APP_APP_PROD
```
## 配置项详解
覆盖在启动时由 `utility/config` 叠加生效。
### 应用配置 `[APP]`
## .env.example
| 变量 | 默认值 | 说明 |
|------|--------|------|
| `DEFAULT_TIMEZONE` | `Asia/Shanghai` | 默认时区 |
| `DEMO` | `false` | 演示模式，开启后拦截所有写操作 |
| `SHOW_ERROR_MSG` | `true` | 是否显示错误详情，生产环境设为 `false` |
全局变量（不属于任何分组）：
| 变量 | 默认值 | 说明 |
|------|--------|------|
| `APP_DEBUG` | `true` | 调试模式，生产环境设为 `false` |
### 数据库配置 `[DATABASE]`
| 变量 | 默认值 | 说明 |
|------|--------|------|
| `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 配置 `[JWT]`
| 变量 | 默认值 | 说明 |
|------|--------|------|
| `SECRET` | 内置默认值 | 签名密钥，**生产环境务必修改** |
| `ACCESS_TTL` | `7200` | access_token 有效期（秒），默认 2 小时 |
| `REFRESH_TTL` | `604800` | refresh_token 有效期（秒），默认 7 天 |
| `ISSUER` | `rxthinkcmf` | 签发者标识 |
### 文件上传配置 `[FILE]`
| 变量 | 默认值 | 说明 |
|------|--------|------|
| `UPLOAD_DIR` | - | 上传根目录（绝对路径） |
| `DOMAIN_URL` | - | 文件访问域名 |
| `IMAGE_EXT` | `gif,jpg,jpeg,png,bmp,webp,svg` | 允许的图片后缀 |
| `FILE_EXT` | 多种后缀 | 允许的文件后缀 |
| `MAX_SIZE` | `10` | 单文件最大大小（MB） |
### 缓存配置 `[CACHE]`
| 变量 | 默认值 | 说明 |
|------|--------|------|
| `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 配置 `[CORS]`
| 变量 | 默认值 | 说明 |
|------|--------|------|
| `ALLOW_ORIGIN` | `*` | 允许的来源，`*` 表示所有 |
### 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` | 模块应用名（影响路由前缀和前端目录） |
## 多环境配置
### 开发环境
```ini
; 开发环境配置（调试开启，使用文件缓存）
APP_DEBUG = true ; 开启调试模式
[APP]
SHOW_ERROR_MSG = true ; 显示错误详情
[DATABASE]
DEBUG = true ; 显示执行的 SQL
[CACHE]
DRIVER = file ; 使用文件缓存（无需 Redis）
```
### 生产环境
```ini
; 生产环境配置（调试关闭，使用 Redis 缓存）
APP_DEBUG = false ; 关闭调试模式
[APP]
SHOW_ERROR_MSG = false ; 不显示错误详情（防止泄露）
[DATABASE]
DEBUG = false ; 不显示 SQL
[CACHE]
DRIVER = redis ; 使用 Redis 缓存
REDIS_HOST = 127.0.0.1 ; Redis 地址
REDIS_PORT = 6379 ; Redis 端口
REDIS_PASSWORD = <你的Redis密码> ; Redis 密码
[JWT]
SECRET = <随机生成的强密钥> ; 签名密钥（必须修改）
[CORS]
ALLOW_ORIGIN = https://admin.example.com ; 限制为实际域名
```
### 生成强密钥
根目录 `.env.example` 是环境变量样例，复制为 `.env` 后按需修改：
```bash
# Linux / macOS：使用 OpenSSL 生成 32 字节随机 Base64 字符串
openssl rand -base64 32
# PHP：生成 32 字节随机十六进制字符串（64 个字符）
# random_bytes(32) → 32 字节密码学安全随机数
# bin2hex() → 转为十六进制字符串
php -r "echo bin2hex(random_bytes(32));"
cp .env.example .env
```
## 前端环境变量
样例包含数据库、Redis、JWT 密钥、文件域名等友好名映射（docker-compose 经 `environment` 块把友好名转成 `APP_` 规范键）。
前端使用 Vite 的环境变量机制，配置文件位于 `ui/` 目录：
:::warning 硬检查
新增配置键必须同步更新 `.env.example`——`make check-config`（`cmd/api -check-config`）会硬检查两者的键一致性，不一致直接失败。
:::
### `.env.development`（开发环境）
## 生产模式要点
```bash
# API 接口基础路径（Vite 代理会将此路径的请求转发到后端）
VITE_GLOB_API_URL=/api
`app.prod=true` 时启动校验将拒绝：
# API 前缀（一般留空）
VITE_GLOB_API_URL_PREFIX=
- 默认或过短的 JWT 密钥
- 非空的验证码万能码（captcha.bypassCode）
- 未关闭的代码生成器（generator.enable）
# 是否启用 Mock 数据（false = 使用真实后端 API）
VITE_USE_MOCK=false
```
生产部署必须开启 prod 并关闭文档端点（`api.docs=false`）。详见 [11.8 安全加固清单](/zh/deploy/security.html)。
### `.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/backend-start.html)