ThinkPHP白名单不生效的四大原因：中间件未在app/middleware.php注册；白名单匹配误用$request->url()而非$request->path()；白名单中间件未置数组首位导致执行顺序靠后；路径配置写死未解耦。
中间件注册位置写错导致白名单不生效
ThinkPHP 的全局中间件必须在
中注册，而不是在控制器或路由闭包里加。很多人把白名单逻辑塞进
后就以为完事了，但没在
里声明，中间件根本不会跑。
实操建议：
立即学习
“
PHP免费学习笔记（深入）
”；
确认
返回的数组里包含你的中间件类，例如：
如果用的是多应用模式，注意路径是
，别改错文件
中间件类名必须带完整命名空间，漏掉
或拼错大小写都会静默失败
白名单匹配逻辑没覆盖请求路径的真实格式
ThinkPHP 路由解析后，
返回的是带 query string 的完整路径（如
），而多数人只按
写白名单，结果匹配失败。
实操建议：
立即学习
“
PHP免费学习笔记（深入）
”；
白名单应基于
（不含 query 和域名），不是
统一用小写 + 去首尾斜杠处理，避免大小写或前缀差异：例如
支持通配符时别用正则硬写，直接用
判断前缀更稳，比如
中间件执行顺序导致鉴权被绕过
如果白名单中间件放在
或
之后，那它根本没机会拦截——请求先被其他中间件拒掉了。白名单必须是「最先执行」的权限校验环节。
实操建议：
立即学习
“
PHP免费学习笔记（深入）
”；
在
数组中，把白名单中间件放在最前面
若使用路由级中间件（
），确保没在某个分组里漏掉它
用
查看实际加载顺序，验证是否真排第一
配置项没从环境变量或配置文件解耦
把白名单路径写死在中间件 PHP 文件里，上线后改个接口就要发版，还容易误提交测试路径到生产环境。
实操建议：
立即学习
“
PHP免费学习笔记（深入）
”；
在
加一项：
中间件里用
读取，方便不同环境配不同列表
如果路径含变量（如
），不要在配置里写通配符，改用中间件内硬编码规则判断，避免配置层过度复杂
白名单真正的难点不在写代码，而在厘清「谁在什么时候看到什么路径」——
、
、路由定义里的
、Nginx 重写后的 URI，这四者经常不一致。调的时候别只看浏览器地址栏，用
打印出来比对最靠谱。
app/middleware.phpapp/common/middleware/CheckWhitelist.phpmiddleware.phpapp/middleware.php[\app\common\middleware\CheckWhitelist::class]app/{app_name}/middleware.php\app\$request->url()/api/user/info?id=123/api/user/info$request->path()$request->url()trim(strtolower($request->path()), '/')str_starts_with()str_starts_with($path, 'api/public/')TokenAuthCheckLoginapp/middleware.phpRoute::middleware()php think middleware:statusconfig/app.php'whitelist_paths' => ['api/health', 'api/v1/public']config('app.whitelist_paths')api/user/:id$request->path()$request->url()api/user/:idLog::info(['path' => $request->path(), 'url' => $request->url()])