ThinkPHP环境搭建中的常见坑与避雷_环境依赖与配置规范-ThinkPHP-PHP中文网

thinkphp 安装与运行常见问题包括：php 版本不匹配（tp6.x 需 php ≥ 7.1，推荐 7.3–8.1）、.env 文件编码或位置错误导致配置未加载、web 服务器未正确传递 path_info 引发路由 404、runtime 目录权限不足及 cli 与 web 环境 php 配置不一致。

thinkphp环境搭建中的常见坑与避雷_环境依赖与配置规范

PHP 版本与 ThinkPHP 版本不匹配导致 `composer create-project` 失败

ThinkPHP 6.x 要求 PHP ≥ 7.1，但实际项目中常因系统默认 PHP 版本过低（如 Ubuntu 自带的 PHP 7.0 或 CentOS 7 的 PHP 5.4）直接报错：require ext-json * -> the requested PHP extension json is missing from your system。这不是 JSON 扩展真没装，而是 PHP 版本太旧，连扩展加载机制都不兼容。

实操建议：

先运行 php -v 确认当前 CLI 使用的 PHP 版本，不是网页里 phpinfo() 显示的那个（常见于多版本共存环境）
ThinkPHP 6.0–6.2 推荐锁定 PHP 7.3–8.1；TP 7.0（beta）已要求 PHP 8.1+，别盲目升级
用 update-alternatives --config php（Debian/Ubuntu）或 alternatives --config php（CentOS）切换 CLI 默认版本，而非仅改 httpd.conf 或 php.ini
Composer 安装时显式指定 PHP 运行器：php7.4 /usr/bin/composer create-project topthink/think tp6

`.env` 文件未生效或被缓存导致数据库连不上

ThinkPHP 启动后读不到 .env 里的 DB_HOST，却坚持用默认的 127.0.0.1，甚至清了 runtime/cache/ 也无效——大概率是 .env 文件编码为 UTF-8 with BOM，或文件权限导致框架根本没读取它。

实操建议：

用 file .env 检查编码，确保是 UTF-8 without BOM；Windows 记事本保存的 .env 几乎 100% 带 BOM
确认 .env 位于项目根目录（即和 think 可执行文件同级），不是放在 public/ 或 app/ 下
检查 think 命令入口是否被修改过：原生 TP 6 的 think 脚本会自动加载 .env，若手动改写过 index.php 入口、绕过了 thinkphp/base.php 初始化流程，则 .env 不会被解析
临时加一行调试：var_dump($_ENV['DB_HOST'] ?? 'not loaded'); 放在 app/common.php 开头，验证是否加载成功

Apache 或 Nginx 配置遗漏 `PATH_INFO` 导致路由 404

访问 /index.php/user/index 正常，但去掉 index.php 就 404，且 url_route_on 已开启——问题不在 TP 配置，而在 Web 服务器没把请求正确转发给 PHP，$_SERVER['PATH_INFO'] 为空或错乱。

btpanel phpsite 宝塔面板PHP网站

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

实操建议：

Apache 必须启用 mod_rewrite，且项目根目录 .htaccess 不能被 AllowOverride None 屏蔽；检查 httpd.conf 或虚拟主机配置中是否有 AllowOverride All

Nginx 用户注意：官方文档给的配置片段里 fastcgi_split_path_info 正则容易写错，TP 6 默认用 PATH_INFO 模式，推荐用更稳的写法：

location ~ \.php(.*)$ {
    fastcgi_pass   127.0.0.1:9000;
    fastcgi_index  index.php;
    fastcgi_split_path_info  ^((?U).+\.php)(/?.+)$;
    fastcgi_param  SCRIPT_FILENAME  $document_root$fastcgi_script_name;
    fastcgi_param  PATH_INFO  $fastcgi_path_info;
    include        fastcgi_params;
}

验证是否生效：在控制器里打印 var_dump($_SERVER['PATH_INFO'] ?? 'empty');，正常应输出类似 /user/index，而不是空或 /index.php/user/index

Runtime 目录权限不足引发 `mkdir(): Permission denied`

部署到 Linux 生产环境时，runtime/log/ 或 runtime/cache/ 写入失败，错误堆栈指向 thinkphp/library/think/Cache.php 第 123 行——本质是 Web 进程用户（如 www-data 或 nginx）对 runtime 目录无写权限，或 SELinux 限制未关闭。

实操建议：

不要 chmod 777 runtime，风险太大；应改为：chown -R www-data:www-data runtime（Debian/Ubuntu）或 chown -R nginx:nginx runtime（CentOS）
确认 Web 进程用户真实身份：ps aux | grep -E '(apache|httpd|nginx|php-fpm)'，别只信配置文件写的用户
SELinux 用户必须执行：semanage fcontext -a -t httpd_sys_rw_content_t "/path/to/your/project/runtime(/.*)?"，再 restorecon -Rv /path/to/your/project/runtime
TP 6.1+ 支持自定义 runtime 路径，在 config/app.php 中设 'runtime_path' => '/var/tmp/tp6_runtime/',，避开项目目录权限纠缠

最常被忽略的是 CLI 和 Web 环境 PHP 配置不一致——比如 php.ini 里 date.timezone 或 extension=openssl 在 CLI 下开着，Web 下却关了，结果命令行能跑迁移，浏览器一访问就报 Class 'OpenSSL\PublicKey' not found。上线前务必用 php -i | grep -E '(timezone|openssl)' 和 php -r "print_r(get_loaded_extensions());" 分别核对两处环境。