必须保留APP_ENV、APP_DEBUG、DB_HOST、DB_PORT、DB_NAME、DB_USER、DB_PWD、DB_PREFIX、REDIS_HOST、REDIS_PORT、REDIS_DATABASE；禁用注释、INI分段、等号空格；值含特殊字符须加单引号；.env.example仅作说明，实际生效的是.env及环境专属文件。
ThinkPHP .env.example 该保留哪些键值对
它不是模板，而是开发协作时的“变量说明书”——只列项目实际用到、且需被不同环境覆盖的变量，其他一律删掉。保留太多会误导新成员以为都要填，删掉关键项又会导致本地启动失败。
必须保留的最小集合（按使用频率排序）：
-
APP_ENV：框架靠它决定加载.env.dev还是.env.prod，不写就永远 fallback 到 production -
APP_DEBUG：开发时开，上线必须关，env('APP_DEBUG')在中间件和异常处理里直接控制行为分支 -
DB_HOST、DB_PORT、DB_NAME、DB_USER、DB_PWD：只要用了数据库，这五个就得明文列出，哪怕.env里留空（值由具体环境文件覆盖） -
DB_PREFIX：如果config/database.php中写了'prefix' => env('DB_PREFIX', '')，就必须出现在 example 里，否则新人 clone 后运行php think migrate会建错表名 -
REDIS_HOST、REDIS_PORT、REDIS_DATABASE：只要config/cache.php或config/session.php显式引用了这些变量，就得列出来
.env.example 里绝对不能出现的内容
ThinkPHP 8.x 的 env() 函数不解析 INI 风格分段，也不读注释行，更不会跳过空格。所以以下写法全无效，还容易引发误操作：
- 带空格的等号：
DB_HOST = 127.0.0.1→ 必须写成DB_HOST=127.0.0.1 - INI 分段：
[database]开头的块 → ThinkPHP 直接忽略整行 - 注释行：
# This is a comment或;开头 →vlucas/phpdotenv不支持，会被当无效键名处理 - 未在代码中实际调用的变量：比如写了
MAIL_FROM，但config/mail.php里根本没用env('MAIL_FROM')→ 新人会困惑要不要配，还可能误填敏感信息
特殊字符和默认值怎么写才安全
值里含 @、!、#、空格等，不加引号会导致解析截断。但 ThinkPHP 8 的 env() 对单引号/双引号处理一致，优先选单引号更省事：
立即学习“PHP免费学习笔记（深入）”；
- 密码含特殊字符：
DB_PWD='pass@123!'✅，DB_PWD=pass@123!❌（@被当分隔符） - URL 类型值：
API_BASE_URL='https://api.example.com/v1'✅，不加引号时//会被当注释起点 - 布尔开关统一用小写字符串：
LOG_QUERIES=true，后续在配置里用filter_var(env('LOG_QUERIES'), FILTER_VALIDATE_BOOLEAN)转换 - 所有变量都应提供默认值占位，例如
REDIS_AUTH=''，避免env('REDIS_AUTH')返回null导致连接器拼出auth=null报错
为什么改了 .env.example 却没生效
因为 .env.example 本身不参与运行——它只是给人看的。真正起作用的是项目根目录下的 .env（通用变量）+ .env.dev 等环境专属文件。常见误区：
- 把
.env.example直接重命名为.env就以为完事 → 必须确认它是 UTF-8 无 BOM 编码，Windows 记事本保存默认带 BOM，会静默失效 - 修改了
.env.example但没同步更新所有.env.*文件 → 比如新加了SENTRY_DSN，却只在.env.dev里补，上线后.env.prod缺失，env('SENTRY_DSN')返回空字符串，Sentry 客户端初始化失败但不报错 - CLI 命令（如
php think migrate）不自动加载.env→ 必须在think文件末尾手动加\Dotenv\Dotenv::createImmutable(__DIR__)->safeLoad();
最常被忽略的一点：所有 .env.* 文件必须和 .env.example 保持字段严格对齐。少一个 DB_PREFIX，开发环境跑得通，上线就查不到带前缀的表；多一个没人用的 OLD_CONFIG，CI 流程里可能意外注入到容器环境变量，干扰其他服务。
