Ubuntu 上跑 ThinkPHP，真正容易出问题的往往不是“安装”这一步，而是版本、重写规则、目录权限和运行环境这些细节没有对齐。本文按部署时最常见的排查顺序，把 ThinkPHP 在 Ubuntu 上集成时需要确认的关键点逐项展开；看完后，你可以判断问题更可能出在 PHP 环境、Web 服务器、项目权限，还是数据库与安全配置上。
先检查环境兼容性，别一开始就卡在版本和扩展上
ThinkPHP 能不能正常启动，首先取决于 PHP 版本和扩展是否满足要求。这里建议先把运行环境核对清楚，再继续做 Web 服务器和项目配置。
确认 PHP 版本是否符合框架要求
不同版本的 ThinkPHP 对 PHP 版本有明确要求：
- ThinkPHP 5.0 及以上要求
PHP 5.6.0+ - ThinkPHP 6.0 要求
PHP 7.2.5+
先用下面的命令确认当前环境版本：
php -v如果版本不匹配，框架可能直接无法运行，后面的配置再完整也没有意义。
把常用 PHP 扩展一次装齐
ThinkPHP 项目常见依赖的扩展包括：
php-mysql：数据库连接php-mbstring：多字节字符串处理php-xml：XML 解析php-curl：HTTP 请求php-openssl：加密能力
可以直接执行：
sudo apt install php-mysql php-mbstring php-xml php-curl php-openssl扩展缺失时，典型表现就是页面报错、某些功能异常，或者依赖安装后运行不完整。
Apache 和 Nginx 怎么配，关键在 public 目录和重写规则
ThinkPHP 对 URL Rewrite 依赖很明显，因此无论你用 Apache 还是 Nginx，都要把入口文件和转发规则配置正确。另一个容易忽略的点是，Web 根目录应指向 public，而不是项目根目录。
Apache 部署时要启用 mod_rewrite
如果使用 Apache，先启用重写模块：
sudo a2enmod rewrite然后修改虚拟主机配置文件，例如 /etc/apache2/sites-available/000-default.conf。部署 ThinkPHP 时，建议将 DocumentRoot 指向项目的 public 目录，并启用：
AllowOverride All，让.htaccess生效- 正确的
DocumentRoot，避免敏感目录暴露
修改完成后重启 Apache：
sudo systemctl restart apache2Nginx 重点看 try_files 和 PHP-FPM socket
Nginx 需要正确处理 Pathinfo 和 URL Rewrite。常见配置核心如下：
location / {
try_files $uri $uri/ /index.php$query_string;
}这条规则的作用，是把找不到实际文件或目录的请求转发到 index.php，否则 ThinkPHP 路由很容易直接变成 404。
同时还要配置 PHP 处理块，并指定 fastcgi_pass 为 PHP-FPM 的 socket 路径，例如：
location ~ .php$ {
fastcgi_pass unix:/run/php/php8.1-fpm.sock;
}改完后重启 Nginx：
sudo systemctl restart nginx权限和 URL 重写为什么总出问题
项目能访问首页，但缓存、日志、上传或路由异常，很多时候都和目录权限、入口目录或重写规则没有配置好有关。这一部分通常是 Ubuntu 下最容易反复折腾的地方。
先把项目所有权和基础权限理顺
Web 服务器用户通常是 www-data。如果它对项目目录没有合适的读写权限，应用可能会出现文件无法访问、缓存写不进去、日志生成失败等问题。
可执行：
sudo chown -R www-data:www-data /path/to/your_project
sudo chmod -R 755 /path/to/your_project这两步分别用于修改所有权和设置基础权限。
runtime 目录必须可写
ThinkPHP 的 runtime 目录承担缓存、日志等临时文件写入，如果这里不可写，排错体验会非常差。可执行：
sudo chmod -R 755 runtime如果项目已经能打开页面，但缓存不生效、日志没有生成，优先检查这一项。
Apache 与 Nginx 的重写规则要分别核对
Apache 项目根目录下的 .htaccess 可以写成：
Options +FollowSymlinks -Multiviews
RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^(.*)$ index.php/$1 [QSA,PT,L]
前提是 Apache 已启用 mod_rewrite，否则这个文件不会生效。
Nginx 则主要依赖：
location / {
try_files $uri $uri/ /index.php$query_string;
}这一项没配时，最直接的现象就是路由全部失效，访问页面返回 404。
Composer 和数据库配置，决定项目能不能真正跑起来
Web 层配置完成后，接下来要处理的是框架依赖和数据库连接。很多“页面白屏”或“启动报错”本质上都出在这里。
优先用 Composer 创建和安装项目
推荐通过 Composer 安装 ThinkPHP，能减少手动下载带来的依赖缺失问题：
composer create-project topthink/think your_project_name例如项目名可以使用 tp6。如果项目已经存在，则进入项目目录执行：
composer install需要更新依赖时再使用：
composer update但更新前要确认版本兼容性，避免把可运行环境直接升级坏。
数据库连接信息尽量放在 .env
数据库配置建议修改项目根目录下的 .env 文件，而不是直接改 config/database.php，这样更适合区分环境，也能降低敏感信息进入版本控制的风险。
典型配置如下：
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=your_db
DB_USERNAME=your_user
DB_PASSWORD=your_pwd这里的参数必须与 Ubuntu 服务器上的 MySQL 实际配置一致。只要主机、端口、用户名或密码其中一项写错，就会出现连接失败。
上线前的安全收尾和故障排查不能省
项目能运行只是第一步。真正部署到 Ubuntu 服务器后，还需要把调试信息、Web 根目录和 HTTPS 等基础安全项补齐，同时准备好日志排查手段。
生产环境至少完成这几项安全配置
首先，在生产环境关闭调试模式：
APP_DEBUG=false开启调试模式会暴露数据库结构、报错栈和部分代码逻辑，不适合对外环境。
其次，Web 服务器的根目录要指向 public，例如 Nginx 中可设置：
root /path/to/tp6/public这样可以避免用户直接访问 app、config 等敏感目录。
另外，还可以在 php.ini 中通过 disable_functions 禁用 eval()、exec()、system() 等危险函数，修改后重启 PHP-FPM 或 Apache 使配置生效。
HTTPS 建议直接用 Let's Encrypt
如果使用 Nginx，可安装：
sudo apt install certbot python3-certbot-nginx如果使用 Apache，则安装：
sudo apt install certbot python3-certbot-apache按提示配置证书即可。HTTPS 已经不是加分项，而是基本要求。
出错时先看日志，再检查配置语法
日志通常比反复猜原因更有效。常见位置包括：
- Apache：
/var/log/apache2/error.log - Nginx：
/var/log/nginx/error.log - PHP：
/var/log/php8.1-fpm.log（具体路径可能随版本变化）
例如：
- 出现 502，常见原因是 PHP-FPM 没启动或 socket 配错
- 路由失效，优先检查 PATHINFO 或 Rewrite 配置
修改 Web 服务器配置后，记得先做语法检查：
sudo nginx -t
sudo apachectl configtest先确认配置文件本身没有语法错误，再重启服务，能省掉很多无效排查时间。
