Webman 项目配置必须集中于 config/ 目录的 PHP 文件，禁用 $GLOBALS、global 和 define()；敏感项走 .env + env()，业务代码只调用 config() 获取已合并、类型安全的配置副本。
Webman 项目里不该用 $GLOBALS 或 global 关键字塞一堆全局变量，也不该在多个文件里零散定义 define() 常量。配置项必须集中、可读、可环境隔离，否则上线后改个数据库密码都要 grep 十分钟。
config/ 目录下统一用 PHP 数组返回配置
所有业务相关配置（如 API 密钥、开关、路径前缀）都应写进 config/ 下的 PHP 文件，例如 config/app.php 或自建的 config/custom.php：
return [
'api_timeout' => 5,
'upload_max_size' => 10 * 1024 * 1024,
'feature_flags' => [
'enable_ai_chat' => env('ENABLE_AI_CHAT', false),
'use_redis_cache' => true,
],
];这样做的好处是：
- 配置和逻辑完全分离，
env()只出现在配置文件里，业务代码里只调用config('custom.api_timeout') - 支持多层嵌套，天然适配复杂结构（比如不同环境的 Redis 连接参数）
- Webman 的
config()函数会自动合并多级数组，无需手动array_merge - 不会污染全局符号表，避免命名冲突或意外覆盖
禁止在业务文件中用 define() 定义运行时常量
define('PAYMENT_GATEWAY', 'alipay'); 看似简洁，但问题明显：
立即学习“PHP免费学习笔记（深入）”；
- 无法被
config()统一管理，不能按环境覆盖（比如测试环境想切到 mock 网关） - 一旦定义就不可修改，调试时无法临时 patch
- IDE 无法跳转到定义处，
grep PAYMENT_GATEWAY可能扫出几十个无关的第三方库常量 - 与 Webman 的配置热加载机制不兼容（
process:reload后define不会重执行）
正确做法是把这类值放进 config/payment.php，再通过 config('payment.gateway') 获取。
env() 和 config() 的调用时机与作用域差异
env() 只应在配置文件中调用，且仅用于读取环境变量；config() 才是业务代码里唯一推荐的配置访问方式：
-
env('DB_HOST')在config/database.php中可用，在控制器里调用属于反模式 -
config('database.host')是安全的，它返回的是已解析、已合并、已类型转换后的最终值 - 如果需要动态计算配置（比如根据 CPU 核心数设进程数），必须在
config/process.php里做，而不是在start.php里手动改Worker::$count -
config()返回的是副本，修改它不会影响原始配置 —— 这是刻意设计，防止业务代码意外污染配置状态
敏感配置必须脱离代码，走 .env + env() 隔离
数据库密码、OpenAI Key、JWT Secret 这类值绝不能硬编码在 PHP 配置文件里：
- 把它们写进项目根目录的
.env文件：DB_PASSWORD=abc123 - 在
config/database.php中用env('DB_PASSWORD')读取 - 确保
.env加入.gitignore，CI/CD 流水线通过 secrets 注入环境变量 - 注意：Webman 默认使用
vlucas/phpdotenv，不支持env('KEY', null)这种带默认值的写法 —— 必须显式传第二个参数，比如env('KEY', '')
真正容易被忽略的是：Webman 的配置系统在进程启动时只加载一次，.env 文件修改后必须重启服务才生效，这点和 Laravel 的 runtime 重载不同。别指望改完 .env 刷新页面就能看到效果。
