Collection::macro()必须在AppServiceProvider::boot()中注册，否则因宏表冻结导致调用时报Method does not exist；闭包内$this指向当前实例（如Collection），宏文件须无命名空间、use或类定义，且需校验命名冲突并加前缀防覆盖。
Collection::macro() 必须在 boot() 里注册，否则调用就报错
宏不是“写完就能用”的东西。Laravel 的 Collection 类在首次被实例化（比如某处调用了 collect([])）时，内部的宏表就已冻结。之后再执行 Collection::macro() 不会报错，但闭包根本不会挂上去——调用时直接抛 BadMethodCallException: Method xxx does not exist。
常见错误位置包括：AppServiceProvider::register()、控制器方法里、配置文件中、路由闭包里、中间件构造函数中。这些地方要么容器未就绪，要么类已被加载，全部无效。
正确做法只有一处：AppServiceProvider::boot()。哪怕只是临时测试，也得确保它在这个方法里执行。Tinker 里可以破例，因为它是独立运行时上下文。
闭包里的 $this 指向当前实例，不是请求或响应上下文
写宏时最常踩的坑是误以为 $this 是全局对象或能自动访问其他依赖。实际上：
-
Collection::macro('isEvenCount', function () { return $this->count() % 2 === 0; })→$this就是Illuminate\Support\Collection实例 -
Request::macro('isAdmin', function () { return $this->segment(1) === 'admin'; })→$this就是Illuminate\Http\Request实例，可直接调$this->input()、$this->route() -
Response::macro('success', function ($data) { return response()->json($data); })→$this是Illuminate\Contracts\Routing\ResponseFactory（即response()返回的对象），不是Request，不能读$request；要用request()辅助函数显式取
宏文件不能有命名空间、use 或类定义
想把宏集中管理？可以新建 app/Macros/CollectionMacros.php，但这个文件必须是“裸文件”：
- 不能有
namespace声明 - 不能有
use语句（所有类名必须全限定，如Illuminate\Support\Collection） - 不能定义任何类、函数或 trait
- 只能写一行行的
Collection::macro(...)调用
然后在 AppServiceProvider::boot() 中用 require_once app_path('Macros/CollectionMacros.php') 引入。漏掉任一限制，PHP 解析就会失败或宏不生效。
命名冲突静默覆盖，IDE 完全不提示
Laravel 对宏名不做校验。如果你注册了 Collection::macro('toJson', ...)，它会直接覆盖原生的 toJson() 方法，且不警告。线上行为可能突变，排查极难。
解决办法只有两个：
- 注册前查文档或源码，确认目标类是否已有同名方法（比如
toCsv、chunkBy、implode都是真实存在的） - 强制加项目前缀，例如用
appToJson()、myChunkBy()，而不是追求“语义干净”
另外，PHPStorm 等 IDE 默认完全看不到宏方法，跳转、补全、类型推导全失效。这不是配置问题，是机制限制——宏方法不在类定义里，静态分析器根本无法感知。
