Laravel 不会自动加载全局辅助函数，必须将 helpers.php 放在 app/Helpers/ 并在 composer.json 的 "autoload"."files" 中显式声明，运行 composer dump-autoload 生效；需避免命名冲突、确保部署包含该配置，并注意路径相对于项目根目录。
全局辅助函数文件放哪才被自动加载
Laravel 不会自动扫描或加载任意 PHP 文件里的函数，helpers.php 必须放在 Composer 的自动加载规则里，否则函数根本不存在。
最稳妥的位置是 app/Helpers/（自建目录），然后在 composer.json 的 "autoload" → "files" 数组中显式声明：
{
"autoload": {
"files": [
"app/Helpers/helpers.php"
]
}
}
- 别放
app/根目录下——容易和模型、服务混淆，且 Laravel 官方 autoload 规则默认不扫它 - 别用
psr-4加载函数文件——PSR-4 只认类，函数会被忽略 - 改完记得运行
composer dump-autoload，否则新函数不生效
函数命名冲突怎么避不开
Laravel 自带的 str、arr、value 等辅助函数都是全局作用域，你定义同名函数时 PHP 会直接报 Fatal error: Cannot redeclare xxx()。
- 优先用前缀，比如
my_format_phone()而不是format_phone() - 检查是否已有同名函数：运行
php -r "var_dump(function_exists('xxx'));" - 别抄 Laravel 源码里的函数名（如
retry()、tap()），它们在vendor/laravel/framework/src/Illuminate/Support/helpers.php里已定义
为什么 artisan tinker 里能用，但 HTTP 请求里报 undefined function
常见原因是 composer dump-autoload 没跑，或者用了 --no-dev 部署，导致 autoload_files.php 里漏掉了你的 helpers。
- 检查
vendor/autoload.php是否最终包含了你的文件路径（可 grep 查找） - 部署时别加
--no-dev后还删了composer.json里的"files"——它不属于 dev-only - 如果用 Swoole 或 Octane，启动后修改 helpers 文件不会热更新，必须重启服务
要不要把 helpers 写成类静态方法更安全
可以，但没必要。全局函数轻量、调用直接，只要避开命名冲突和加载问题，比 Helper::xxx() 更符合 Laravel 社区习惯。
- 如果函数逻辑复杂、依赖多、需要 mock 测试，才值得封装成类
- 纯工具函数（比如字符串截断、数组扁平化）保持函数形式更自然
- 注意：类静态方法无法被 IDE 自动补全函数签名，而全局函数在 PHPStorm 中配合
@method注解也能有提示
真正容易被忽略的是 autoload 文件路径的相对性——app/Helpers/helpers.php 是相对于项目根目录，不是 vendor/ 或 bootstrap/ 目录。写错一个点，就等于没加载。
