一句话总结：在 ThinkPHP 6+ 中定义全局助手函数时，必须放在app/common.php或app/common/目录下且文件名为common.php，同时不能声明命名空间；如果要重载框架内置函数，必须先使用function_exists()做存在性判断；修改完成后还需要执行composer dump-autoload并清理配置缓存，函数才能正常生效。
助手函数文件该放在哪、怎么命名才会被自动加载
很多开发者以为随手写一个 _common.php 就能在 ThinkPHP 中自动加载，但在 ThinkPHP 6+ 里并不是这样。框架对于全局助手函数文件的位置和命名有明确要求：文件路径必须是 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() 返回的是整个 ThinkPHP 项目的根目录，并不是 app/ 目录本身；而 app/ 是应用目录，所以全局助手函数文件必须基于这个项目根目录来正确放置。
函数定义时不能使用命名空间，但一定要避免重名冲突
所有写在 app/common.php 或 app/common/*.php 中的自定义函数，都会被直接加载到全局作用域中。这也意味着这里不能声明 namespace，通常也不适合写 use 导入代码——否则很容易触发 Fatal error: Namespace declaration statement must be at the beginning 这类错误。
也正因为这些 ThinkPHP 助手函数处于全局作用域，函数名冲突的风险会明显增加。比如你定义了一个 format_date()，而某个 Composer 第三方扩展包恰好也提供了同名方法，后续加载时就会直接报出 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() 才是 ThinkPHP 框架底层真正的调用入口，千万不要直接去调用 getenv() 或手动读取 $_ENV。否则会绕开 ThinkPHP 对环境变量的解析机制，比如 .env 文件合并、数据类型转换等处理逻辑，后续很容易出现隐藏问题。
修改后不生效？优先检查 Composer 自动加载和缓存问题
在 ThinkPHP 6+ 中，app/common.php 的引入依赖于 Composer 的 files 自动加载机制。如果你已经新增或修改了这个文件，但全局助手函数依然无法调用，通常大概率就是以下两个原因：
- Composer 自动加载没有刷新：请执行
composer dump-autoload，注意这里不是install或update - 项目启用了配置缓存（例如执行过
php think optimize:config）：这种情况下common.php可能不会重新加载，需要先运行php think clear:config清除缓存
补充一点：如果你使用的是 app/common/ 目录下的多个函数文件，一般不需要手动把它们写进 composer.json，因为 ThinkPHP 会按照约定进行自动扫描；但如果你把这些文件移动到了 app/extra/ 或其他非标准目录中，那就必须自行在 composer.json 的 "autoload": {"files": [...]} 中显式注册，否则不会被自动加载。
真正更复杂的情况通常出现在跨模块或跨包复用场景中——例如你在独立的 vendor/my/package 包里也想复用这些 ThinkPHP 全局助手函数，那么就不能继续依赖 app/common.php。更合理的方式是把公共函数单独抽离成独立的 functions.php 文件，并通过 Composer 自动加载进行注册，否则其他扩展包根本无法访问这些函数。
