ThinkPHP安装失败主因是5个隐蔽误区：1.PHP CLI与Web环境不一致，需确认php.ini路径及扩展启用；2..env文件含BOM头致配置未加载；3.误用composer install替代create-project导致框架未初始化；4.Web服务器未正确传递PATH_INFO使路由失效；5.runtime目录权限不足引发假数据库错误。
刚下载完Composer、打开命令行准备安装ThinkPHP，却卡在第一步：php -v显示7.4，但composer create-project报错“require ext-json *”，或者项目跑起来后连不上数据库、路由全404——这些不是你手残，而是90%新手都踩过的5个隐蔽安装误区，每个都足以让开发进度停滞两小时以上。
误区一：PHP版本看似达标，实则CLI与Web环境不一致
运行php -v看到的是7.3，但浏览器访问phpinfo()却是5.6；或者用XAMPP切换了PHP版本，命令行里php -v仍显示旧版。
第一步：在终端执行php -i | grep "Loaded Configuration File"，确认CLI实际加载的php.ini路径。
第二步：对比该php.ini中extension=openssl、extension=json是否已取消注释——Windows下这两个扩展名带.dll后缀，Linux下无后缀，写错就直接报“ext-json missing”。
立即学习“PHP免费学习笔记（深入）”；
第三步：若使用WAMP/XAMPP/PHPStudy，必须进其控制面板单独设置“CLI PHP版本”，不能只改Apache或Nginx的PHP模块。否则composer install和php think永远用不到你以为已启用的扩展。
误区二：.env文件放对了位置，却根本没被读取
数据库配置明明写在.env里，tp6启动后还是连127.0.0.1:3306，【.env文件编码为UTF-8 with BOM是Windows记事本默认行为，ThinkPHP会静默跳过整个文件】。
方法一：用VS Code或Notepad++打开.env → 右下角点击编码 → 选“UTF-8 without BOM” → 保存。
方法二：命令行快速检测（Linux/macOS）：file .env，输出含“with BOM”即需重存；Windows用户可直接执行certutil -hashfile .env MD5，首字节为EF BB BF即为BOM头。
注意：.env必须和think可执行文件同级，放在public/或app/目录下完全无效。
误区三：用composer install代替create-project
从GitHub下载ZIP解压，再进目录执行composer install——这会导致vendor/autoload.php缺失、runtime目录未初始化、app.php未生成，最终报Class 'think\App' not found。
正确路径只有一条：composer create-project topthink/think myproject。
这条命令会自动触发thinkphp/base.php中的初始化逻辑，包括生成.env、清空runtime、写入基础配置；而install只是装依赖，不做任何框架级初始化。
如果已误操作，删掉整个项目重来，别试图补救——runtime缓存、autoload映射、配置合并机制全部错位，越修越乱。
误区四：Web服务器没传PATH_INFO，却怪TP路由失效
访问/index.php/user/index能进控制器，但去掉index.php就404，且config/app.php里url_route_on=true已开启。
Apache用户：检查httpd.conf中LoadModule rewrite_module modules/mod_rewrite.so是否启用，并在虚拟主机配置段内加入AllowOverride All，否则.htaccess文件被完全忽略。
Nginx用户：必须用try_files $uri $uri/ /index.php?$query_string;，不能照搬Apache的.htaccess规则——Nginx根本不识别.htaccess。
验证方式：在项目根目录放test.php，内容为<?php var_dump($_SERVER['PATH_INFO'] ?? 'empty');，访问/test.php时输出为空字符串，说明PATH_INFO未传递，问题100%出在Web服务器配置。
误区五：runtime目录权限设错，错误提示却指向数据库
页面报“SQLSTATE[HY000] [1045] Access denied for user 'root'@'localhost'”，但mysql -u root -p能正常登录，.env里密码也确认无误。
这是因为TP6在连接数据库前，先尝试往runtime/log/写日志文件；【runtime不可写时，框架会伪造一个“数据库连接失败”的假错误，掩盖真实的权限问题】。
Linux/macOS：执行chmod -R 755 runtime/（不要用777）；若仍报错，再执行chown -R www-data:www-data runtime/（Ubuntu）或chown -R apache:apache runtime/（CentOS）。
Windows：右键runtime文件夹→属性→安全→编辑→添加IIS_IUSRS或Users组→勾选“写入”权限→确定。
