debian运行laravel要注意什么

在 Debian 上运行 Laravel（无论是本地开发还是生产环境），有几个系统层面和Laravel 本身的关键点需要注意。下面按“常见坑 + 最佳实践”给你梳理一下。

一、系统与运行环境

1. PHP 版本要符合要求

Laravel 对 PHP 版本要求较新：

Laravel 10：PHP ≥ 8.1
Laravel 11：PHP ≥ 8.2
Laravel 12（最新）：PHP ≥ 8.2

Debian 默认源可能较旧（如 Debian 11 是 PHP 7.4），建议：

sudo apt install lsb-release ca-certificates apt-transport-https software-properties-common
sudo add-apt-repository ppa:ondrej/php  # Ubuntu

⚠️ Debian 没有直接 PPA，可用 deb.sury.org 的源（onrej 维护）

2. 必须安装的 PHP 扩展

Laravel 运行最少需要：

php-cli php-fpm php-mysql php-xml php-mbstring php-curl php-zip php-gd php-bcmath php-intl

常见缺扩展导致的问题：

php-xml 缺失 → Composer 报错
php-mbstring 缺失 → Laravel 无法启动
php-bcmath → 支付/精度计算问题

二、Web 服务器（Nginx / Apache）

3. Nginx 是最常见选择

示例 Nginx 配置要点：

server {
    listen 80;
    server_name example.com;
    root /var/www/laravel/public;

    index index.php;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

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

⚠️ root 必须指向 public/，否则有严重安全风险

三、权限问题（Debian 上最常见坑）

4. 用户与权限

Web 服务用户一般是 www-data
部署用户不要是 root

推荐做法：

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

或更安全方式（推荐）：

sudo usermod -aG www-data youruser

四、Composer 与部署

5. 使用 Composer 正确安装

composer install --no-dev --optimize-autoloader

生产环境不要：

composer install（带 dev 依赖）

6. 关键 Artisan 命令

部署后必须执行：

php artisan config:cache
php artisan route:cache
php artisan view:cache
php artisan migrate --force

五、环境与安全

7. .env 文件安全

.env 不能被 Web 访问
权限：

chmod 640 .env
chown www-data:youruser .env

8. 关闭调试

生产环境：

APP_DEBUG=false
APP_ENV=production

六、队列 / 定时任务（容易被忽略）

9. 队列（Queue）

Laravel 队列不要用 sync

使用：

php artisan queue:work

生产建议：

Supervisor 守护进程

Supervisor 示例：

[program:laravel-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/laravel/artisan queue:work
autostart=true
autorestart=true
user=www-data

10. 定时任务（Task Scheduler）

* * * * * www-data php /var/www/laravel/artisan schedule:run

七、常见问题速查

问题	原因
500 错误	storage 无写权限
白屏	APP_DEBUG=false + 日志未看
路由 404	Nginx try_files 错误
Composer 报错	PHP 扩展缺失
慢	未 cache 配置

总结（最简清单）

✅ PHP ≥ 8.2
✅ Nginx + php-fpm
✅ root = public
✅ storage 可写
✅ composer --no-dev
✅ artisan cache
✅ supervisor + cron

如果你愿意，我可以：

给你一份 Debian + Nginx + Laravel 完整部署脚本
或针对 Debian 11 / 12 具体版本说明
或帮你排查某个具体报错

你现在是 开发环境还是生产服务器？