怎么调试Debian的Laravel

调试 Debian 上的 Laravel，通常分为 环境层面、Laravel 自身、日志与工具 三个层面。下面给你一套从“新手可用”到“进阶定位问题”的完整思路。

一、基础环境确认（90% 的问题都在这里）

1️⃣ PHP 版本 & 扩展

Laravel 对 PHP 版本要求严格：

php -v

常见缺失扩展：

sudo apt install php php-cli php-common php-mysql php-mbstring php-xml php-curl php-zip php-bcmath php-tokenizer

✅ 建议：

Laravel 10 → PHP ≥ 8.1
Laravel 11 → PHP ≥ 8.2

2️⃣ Composer 是否正常

composer -V
composer install

常见问题：

composer install 报权限错误 → 不要用 root 直接跑
内存不足：

php -d memory_limit=-1 /usr/bin/composer install

3️⃣ Web 服务器 & PHP-FPM

Nginx

sudo systemctl status nginx

PHP-FPM

sudo systemctl status php8.2-fpm

Nginx 示例配置（关键）：

location ~ \.php$ {
    include snippets/fastcgi-php.conf;
    fastcgi_pass unix:/run/php/php8.2-fpm.sock;
}

二、Laravel 核心调试方法

1️⃣ 打开调试模式（非常重要）

编辑 .env：

APP_DEBUG=true
APP_ENV=local

⚠️ 生产环境不要用

2️⃣ 查看 Laravel 日志

tail -f storage/logs/laravel.log

常见错误：

SQLSTATE[HY000] [2002] → 数据库没启动
Permission denied → storage / bootstrap 权限问题

3️⃣ 权限问题（Debian 常见）

sudo chown -R www-data:www-data storage bootstrap/cache
sudo chmod -R 775 storage bootstrap/cache

如果你是普通用户开发：

sudo usermod -aG www-data $USER

三、数据库调试

1️⃣ 数据库是否启动

sudo systemctl status mariadb
# 或 mysql

2️⃣ 测试连接

php artisan tinker

DB::connection()->getPdo();

四、路由 & 控制器调试

1️⃣ 查看路由

php artisan route:list

2️⃣ dump 调试

dd($data);
dump($data);

五、使用专业调试工具（强烈推荐）

✅ Laravel Debugbar

composer require barryvdh/laravel-debugbar --dev

访问页面后，底部会出现调试栏。

✅ Xdebug（进阶）

安装

sudo apt install php-xdebug

配置

xdebug.mode=develop,debug
xdebug.start_with_request=yes

配合：

VS Code
PHPStorm

六、快速定位“页面空白 / 500”

打开 APP_DEBUG=true
查看：
- storage/logs/laravel.log
- Nginx：/var/log/nginx/error.log
- PHP-FPM：/var/log/php8.2-fpm.log
权限
Composer 没装完

七、常用排错命令汇总

php artisan config:clear
php artisan cache:clear
php artisan route:clear
php artisan view:clear
php artisan optimize:clear

八、如果你愿意，我可以直接帮你定位

你可以直接贴：

Debian 版本
Laravel 版本
报错信息（完整）
访问页面是 空白 / 500 / 404 / 502

我可以一步一步帮你精确到“哪一行代码出问题”。