在 Linux 上运行 ThinkPHP 的完整步骤

想在 Linux 服务器上顺利跑起 ThinkPHP 框架？别担心，这事儿其实没想象中那么复杂。下面这份从环境准备到问题排查的完整指南，能帮你避开大多数新手容易踩的坑。

一 环境准备

万事开头难，先把基础环境搭建好。这里以 Ubuntu/Debian 和 CentOS/RHEL 两大主流家族为例，包名基本一致，只是包管理器不同。

• 安装 PHP 与常用扩展：ThinkPHP 运行需要一些核心的 PHP 扩展支持，比如数据库驱动、XML 处理和 GD 图像库等。
  • Ubuntu/Debian 用户，请打开终端执行：
    • sudo apt update && sudo apt install -y php php-cli php-fpm php-mysql php-mbstring php-xml php-curl php-zip php-gd php-bcmath
  • CentOS/RHEL 用户，对应的命令是（可能需要先启用 EPEL 仓库）：
    • sudo yum install -y php php-cli php-fpm php-mysqlnd php-mbstring php-xml php-curl php-zip php-gd php-bcmath
• 安装并启动 Web 服务器：Nginx 或 Apache，选一个你熟悉的就行，甚至并存也可以。
  • Nginx：sudo apt/yum install -y nginx && sudo systemctl enable --now nginx
  • Apache：sudo apt/yum install -y apache2/httpd && sudo systemctl enable --now apache2/httpd
• 安装 Composer：这是 PHP 的依赖管理工具，ThinkPHP 的项目创建和包管理都离不开它。
  • 一行命令搞定安装：curl -sS https://getcomposer.org/installer | php
  • 移动到全局路径方便调用：sudo mv composer.phar /usr/local/bin/composer
  • 最后，用 composer --version 验证一下是否安装成功。

二 部署与运行方式

环境齐备，接下来就是部署 ThinkPHP 项目了。这里提供两种主流方式，你可以根据场景选择。

• 方式 A：快速运行（内置开发服务器）

  这种方式最适合本地开发或快速测试，因为它用 PHP 自带的开发服务器，省去了配置 Web 服务器的麻烦。

  • 创建项目：composer create-project topthink tp5 --prefer-dist
  • 进入项目目录：cd tp5
  • 启动内置服务器：php think run
  • 打开浏览器，访问 https://服务器IP:8000（默认监听 8000 端口），就能看到欢迎页面了。
• 方式 B：生产部署（Nginx + PHP-FPM）

  线上环境，我们更推荐这种稳定、高性能的组合。

  • 首先，将你的项目代码上传到服务器站点目录，例如 /var/www/html/your_tp_app。
  • 关键一步：配置 Web 服务器的站点根目录，必须指向项目内的 public 目录。这是 ThinkPHP 的安全设计，将入口文件与核心代码隔离。
  • 接着，配置 URL 重写规则，确保所有请求都能被正确地转发到 public/index.php 这个单一入口文件。
  • 最后，重启 Web 服务和 PHP-FPM，通过域名或 IP 访问，你的应用就应该跑起来了。

三 Nginx 与 Apache 配置要点

上面提到了配置，这里再展开说说两个 Web 服务器的具体配置片段，帮你理清关键点。

• Nginx 站点配置示例

  核心在于两点：一是根目录指向 public，二是配置好 PHP 请求的转发。

  • 核心配置片段：

    root /var/www/html/your_tp_app/public;
    index index.php index.html;
    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }
    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/var/run/php/php7.4-fpm.sock; # 请根据实际 PHP 版本调整
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }
    location ~ /\.ht {
        deny all;
    }

  • 启用并重载配置： sudo ln -s /etc/nginx/sites-a vailable/your_tp /etc/nginx/sites-enabled/ && sudo nginx -t && sudo systemctl reload nginx
• Apache 站点配置示例

  对于 Apache，重点是开启 mod_rewrite 模块并允许目录重写。

  • 核心配置片段：

    DocumentRoot /var/www/html/your_tp_app/public
    
        Options Indexes FollowSymLinks
        AllowOverride All
        Require all granted
    

  • 启用模块并重启： sudo a2enmod rewrite && sudo systemctl restart apache2

四 数据库与目录权限

应用跑起来只是第一步，要让它能正常工作，数据库连接和文件权限这两个“后勤保障”必须到位。

• 数据库配置
  • 找到项目的数据库配置文件（通常是 application/database.php 或 config/database.php），填入你的数据库主机、名称、用户名和密码。如果用的是 MySQL 8，记得留意一下默认的认证插件和字符集设置，避免连接失败。
• 目录权限与运行用户
  • 权限问题是部署中最常见的“拦路虎”。一个稳妥的做法是，将整个站点目录的所有者设置为 Web 服务的运行用户（比如 Ubuntu 下的 www-data 或 CentOS 下的 nginx）。
    • sudo chown -R www-data:www-data /var/www/html/your_tp_app
    • sudo find /var/www/html/your_tp_app -type d -exec chmod 755 {} \;
    • sudo find /var/www/html/your_tp_app -type f -exec chmod 644 {} \;
  • 特别要注意 runtime、storage 这类目录，框架运行时需要向里面写入日志、缓存和会话文件，必须确保它们对 Web 服务用户是可写的。

五 常见问题与排查

即使按照步骤来，偶尔也可能遇到点小麻烦。别慌，下面这些常见问题及其解决方法，能帮你快速定位。

• 404 或路由无效：首先检查站点根目录是否指向了 public 目录。对于 Nginx，确认 try_files 指令正确配置；对于 Apache，确保 mod_rewrite 模块已启用，且目录配置中设置了 AllowOverride All。
• 访问出现空白或语法错误：这通常是 PHP 环境问题。检查 PHP-FPM 服务是否在运行（systemctl status php7.4-fpm），并核对 php.ini 中是否已经启用了所有必要的扩展，如 mbstring、xml、curl、gd、zip、bcmath、pdo_mysql。
• Composer 安装/更新慢或失败：网络问题很常见。可以临时切换为国内镜像加速，例如使用 packagist.phpcomposer.com。也可以尝试先更新 Composer 本身：composer self-update。
• 权限被拒绝或日志写入失败：回头仔细核对目录的所有者和权限设置。确保 runtime、storage 等目录可写，并且 Web 服务进程与 PHP-FPM 进程的运行用户保持一致，能极大减少这类权限冲突。
• 需要外网访问：别忘了在服务器防火墙开放 80（HTTP）和 443（HTTPS）端口。对于生产环境，强烈建议配置 HTTPS，使用 Let’s Encrypt 获取免费 SSL 证书是个不错的选择。