thinkphp 6+ 全局助手函数必须放在 app/common.php 或 app/common/ 目录下命名为 common.php，且不能有命名空间；重载内置函数需用 function_exists() 判断；修改后需执行 composer dump-autoload 并清除配置缓存。
助手函数文件该放在哪、怎么命名才被自动加载
ThinkPHP 6+ 默认不会自动加载任意 _common.php 文件，所谓“全局助手函数”必须满足两个硬性条件：文件路径在 app/common.php（或 app/common/ 目录下），且文件名是 common.php —— 不是 _common.php，也不是 helper.php。很多开发者卡在这一步，放错位置或改了名字，函数就永远不生效。
实际路径只有这两个合法：
-
app/common.php（单文件模式，推荐新手） -
app/common/目录下的多个.php文件（如app/common/string.php），需确保这些文件内只写函数定义，无类、无命名空间、无return
注意：think\facade\App::getRootPath() 返回的根目录不是 app/，而是项目根目录；app/ 是应用目录，必须相对这个路径放置。
函数定义时不能用命名空间，但要防重名冲突
所有写在 app/common.php 或 app/common/*.php 中的函数，都会被直接载入全局作用域。这意味着你不能加 namespace，也不能用 use 导入其他类——否则会报 Fatal error: Namespace declaration statement must be at the beginning。
但正因为没命名空间保护，函数名极易冲突。比如你定义了 format_date()，而某个第三方包也提供了同名函数，后续加载就会触发 Cannot redeclare format_date() 错误。
- 推荐前缀统一，例如
tp_format_date()、tp_log_debug() - 避免短名如
dd()、dump()—— ThinkPHP 自带的think\helper\Str和调试工具已占用了类似语义 - 如果必须复用已有函数名（如重载
env()），得先用function_exists('env')判断，再包裹定义（见下一点）
重载内置函数（如 env()、config()）必须加存在性判断
ThinkPHP 的 env()、config() 等函数由框架在启动早期注册，若你在 app/common.php 里直接重新定义，会因加载顺序问题导致致命错误。正确做法是用 function_exists() 包一层，仅当原函数未定义时才注册你的版本。
示例（安全重载 env()）：
if (!function_exists('env')) {
function env($key = null, $default = null)
{
// 你的增强逻辑，比如支持嵌套键 'database.host'
$value = \think\facade\App::env($key, $default);
return is_string($value) ? trim($value) : $value;
}
}
注意：\think\facade\App::env() 是框架底层真实调用入口，不要直接调用 getenv() 或读取 $_ENV —— 这会绕过 ThinkPHP 的环境变量解析逻辑（如 .env 文件合并、类型转换）。
修改后不生效？检查 Composer 自动加载和缓存
ThinkPHP 6+ 使用 Composer 的 files 自动加载机制来引入 app/common.php。如果你手动新增或修改了该文件，但函数仍不可用，大概率是以下两个原因：
- Composer 没刷新自动加载：执行
composer dump-autoload（不是install或update） - 应用开启了配置缓存（
php think optimize:config）：此时common.php不会被重新载入，需先运行php think clear:config
顺带一提：app/common/ 目录下的多个文件，不需要手动加到 composer.json，框架通过约定自动扫描；但一旦你把文件挪到 app/extra/ 或其他非标准路径，就必须自己在 composer.json 的 "autoload": {"files": [...]} 里显式声明。
真正麻烦的是跨模块场景——比如你在一个独立的 vendor/my/package 里也想用这些助手函数，那就不能依赖 app/common.php，得抽成独立的 functions.php 并注册进 Composer，否则别的包根本看不到。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
