在 Ubuntu 上运行 ThinkPHP 的完整步骤

一 准备环境

万事开头先搭台。想在 Ubuntu 上顺畅跑起 ThinkPHP，第一步就是把基础环境给配齐了。这活儿不复杂，跟着下面几步走就行。

• 更新系统并安装 PHP 及常用扩展（适配 ThinkPHP 常见依赖）：
  • 命令：sudo apt update && sudo apt install -y php php-cli php-fpm php-mysql php-curl php-gd php-mbstring php-xml php-zip
• 安装 Nginx（亦可选择 Apache）：
  • 命令：sudo apt install -y nginx
  • 启动与开机自启：sudo systemctl start nginx && sudo systemctl enable nginx
• 安装 Composer（PHP 依赖管理工具）：
  • 命令：curl -sS https://getcomposer.org/installer | php && sudo mv composer.phar /usr/local/bin/composer
  • 验证：composer -v 应显示版本号

这里有个关键点：ThinkPHP 6 通常要求 PHP 版本不低于 7.2。上面列出的扩展包，基本覆盖了大多数项目的常规需求，一步到位能省去不少后续麻烦。

二 创建与配置项目

环境就绪，接下来就是创建项目并进行关键配置了。这个过程，其实就是在为你的应用“上户口”和“通水电”。

• 使用 Composer 创建项目（以 ThinkPHP 6 为例）：
  • 命令：composer create-project topthink tp
  • 进入目录：cd tp
• 配置数据库（两种常见方式，二选一或并存）：
  • 方式 A（推荐，.env 环境文件）：在项目根目录编辑或创建 .env，设置
    • DB_TYPE=mysql
    • DB_HOST=127.0.0.1
    • DB_NAME=your_db
    • DB_USER=your_user
    • DB_PWD=your_password
    • DB_PORT=3306
  • 方式 B（配置文件）：编辑 config/database.php，填写 type/host/username/password/database/port 等
• 目录权限（Web 写入场景如日志、缓存、上传）：
  • 命令：sudo chown -R www-data:www-data /var/www/html/tp && sudo chmod -R 755 /var/www/html/tp

简单来说，ThinkPHP 支持通过 .env 文件或配置文件来管理数据库这类环境参数。选择哪一种，就看你的项目规范或个人习惯了。

三 运行方式

项目配置好了，怎么让它跑起来？这里得分情况讨论：是图方便的本地开发，还是准备正式上线的生产环境。

• 开发环境快速启动（内置服务器，适合本机或测试）：
  • 命令：php think run
  • 访问：浏览器打开 https://localhost:8000
• 生产环境建议使用 Nginx + PHP-FPM（示例站点配置，/var/www/html/tp 为项目根目录）：
  • 新建站点配置：sudo nano /etc/nginx/sites-a vailable/tp
  • 配置内容：

    server {
        listen 80;
        server_name your_domain_or_ip;
        root /var/www/html/tp/public; # 注意指向 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;
        }
    }

  • 启用站点并重启 Nginx：
    • sudo ln -s /etc/nginx/sites-a vailable/tp /etc/nginx/sites-enabled/
    • sudo nginx -t && sudo systemctl restart nginx
  • 访问：https://your_domain_or_ip

这里有个必须注意的细节：ThinkPHP 6 的 Web 入口在 public/index.php，所以 Nginx 配置里的 root 一定要指向这个 public 目录。至于那个内置服务器，记住它只适合开发阶段临时用用。

四 常见问题与排查

即使步骤都对了，偶尔还是会碰到些小麻烦。别慌，下面这几个是高频问题，对照着排查，基本都能解决。

• 404 或路由无效：确认 Nginx 配置包含 try_files $uri $uri/ /index.php?$query_string; 且 root 指向了 public。
• 类自动加载失败：在项目根目录执行 composer install，确保 vendor/autoload.php 存在并已正确引入。
• 数据库连接失败：仔细核对 .env 或 config/database.php 中的主机、库名、账号、密码、端口；同时确保 MySQL 服务正在运行且允许连接。
• 权限错误：Web 进程（通常是 www-data 用户）需要对 runtime、log、上传等目录有写入权限，检查用户和组权限设置。
• PHP 版本不匹配：ThinkPHP 6 需要 PHP >= 7.2。用 php -v 检查版本，必要时升级 PHP，并记得同步调整 Nginx 配置中 fastcgi_pass 的套接字路径（比如改成 php8.1-fpm.sock）。