ThinkPHP前后端分离新手最常踩的坑是配置错误：路由未隔离导致API被前端路由吞掉；CORS未正确处理OPTIONS预检或credentials与*混用；接口未显式return json()且模板渲染未禁用；Web服务器根目录未指向public目录。
ThinkPHP前后端分离项目新手最常踩的坑，不是代码写错，而是配置环节几个关键点没对上——看似微小，却直接导致接口404、跨域失败、返回乱码或白屏。核心问题集中在路由、跨域、接口输出、环境部署四块。
路由没隔离，前端页面和API互相“抢路”
新手常把所有请求都 fallback 到 index/index，结果连 /api/login 也被当成前端路由处理，后端控制器根本没执行。
- 别用
Route::rule('[:path]', 'index/index')这类无差别兜底，它会吞掉所有路径（包括 /api/xxx） - 必须显式区分：非 API 请求 fallback 到前端入口（如
index.html），API 请求走独立分组 - 推荐写法：
Route::domain('api', function () { Route::group('v1', [...]); });，再配Route::rule('[:path]', 'index/index')->ext('html')（加->ext('html')防止匹配 .json 请求） - 关闭强制路由：
'url_route_must' => false，否则未定义路径直接 404
CORS 配置“半残”，OPTIONS 请求被拦死
浏览器发 OPTIONS 预检时，后端没响应或头信息不全，前端控制台只报“CORS error”，实际是预检没过。
- 别在中间件里直接写
header()—— TP8 的 Response 对象会覆盖它，必须用$response->header() - 带 credentials（如 Cookie 或 Authorization）时，
Access-Control-Allow-Origin不能写*，必须填具体域名数组，比如['http://localhost:5173', 'https://admin.example.com'] - 确保
Access-Control-Allow-Credentials设为true，且与 Origin 域名严格匹配 - 用官方插件更稳：
composer require topthink/think-cors，再在config/cors.php中设好allowed_origins和supports_credentials
接口返回不是纯 JSON，前端收不到 data
明明写了 return json($data)，但前端拿到的是 HTML 模板、空响应或 500 错误——本质是框架还在走视图渲染流程。
立即学习“PHP免费学习笔记（深入）”；
- 控制器方法末尾必须显式
return json(...)，不能依赖自动输出或$this->fetch() - 禁用模板引擎：确保没调用任何视图方法（
fetch、display），控制器继承think\Controller即可，无需额外 base 类 - 检查
config/app.php中'default_return_type' => 'json'只是兜底，不替代显式 return - POST 接收参数注意：Axios 默认发 JSON，
$this->request->param()收不到，改用json_decode($this->request->getContent(), true)
Web 服务器根目录设错，public 没暴露出来
访问域名直接 404 或白屏，不是代码问题，是服务器压根没走到 ThinkPHP 入口。
- Apache/Nginx 的
DocumentRoot或root必须指向项目内的 public 目录，不是项目根目录（含 app/、runtime/ 的那层） - Nginx 示例：
root /path/to/your/project/public;+try_files $uri $uri/ /index.php?s=$uri&$args; - Apache 要启用
.htaccess，并确认AllowOverride All - 验证方式：浏览器访问
http://localhost/public/能看到 ThinkPHP 欢迎页，才算 root 设置正确
