Debian系统如何搭建Laravel的开发环境

在 Debian 上搭建 Laravel 开发环境

一 准备与安装基础组件

• 更新系统并安装常用工具：
  • sudo apt update && sudo apt upgrade -y
  • sudo apt install -y curl git unzip
• 安装 PHP 与常用扩展（以 PHP 8.2 为例，可按需调整版本）：
  • sudo apt install -y php8.2 php8.2-cli php8.2-fpm php8.2-mysql php8.2-json php8.2-xml php8.2-mbstring php8.2-curl php8.2-zip php8.2-gd php8.2-bcmath
  • 启动并开机自启 PHP-FPM：sudo systemctl enable --now php8.2-fpm
• 安装数据库（二选一或两者皆装）：
  • MariaDB：sudo apt install -y mariadb-server && sudo mysql_secure_installation
  • MySQL：sudo apt install -y mysql-server
• 安装 Composer：
  • curl -sS https://getcomposer.org/installer | php
  • sudo mv composer.phar /usr/local/bin/composer && chmod +x /usr/local/bin/composer
  • 验证：composer --version。

二 创建项目与配置环境

• 创建 Laravel 项目（两种常用方式，二选一）：
  • 使用 Composer 直接创建：composer create-project --prefer-dist laravel/laravel my-laravel-app
  • 使用 Laravel 安装器（全局）：composer global require laravel/installer，随后 laravel new my-laravel-app
• 配置 .env 与生成密钥：
  • cd my-laravel-app && cp .env.example .env
  • 编辑 .env 设置数据库等：
    • DB_CONNECTION=mysql
    • DB_HOST=127.0.0.1
    • DB_PORT=3306
    • DB_DATABASE=laravel
    • DB_USERNAME=laravel
    • DB_PASSWORD=your_password
  • 生成应用密钥：php artisan key:generate
• 创建数据库与用户（示例）：
  • mysql -u root -p
  • CREATE DATABASE laravel CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
  • CREATE USER ‘laravel’@‘localhost’ IDENTIFIED BY ‘your_password’;
  • GRANT ALL PRIVILEGES ON laravel.* TO ‘laravel’@‘localhost’;
  • FLUSH PRIVILEGES; EXIT;
• 安装依赖与初始化（开发环境建议以 www-data 运行避免权限问题）：
  • sudo chown -R www-data:www-data storage bootstrap/cache
  • sudo -u www-data composer install
  • sudo -u www-data php artisan migrate --seed（可选：–seed 填充演示数据）

三 配置 Web 服务器

• Nginx 示例站点（/etc/nginx/sites-available/laravel.test）：
  • server {
    • listen 80;
    • server_name laravel.test;
    • root /var/www/my-laravel-app/public;
    • index index.php;
    • add_header X-Frame-Options “SAMEORIGIN”;
    • add_header X-Content-Type-Options “nosniff”;
    • charset utf-8;
    • location / {
      • try_files $uri $uri/ /index.php?$query_string;
      • }
    • location ~ .php$ {
      • include snippets/fastcgi-php.conf;
      • fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;
      • fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
      • include fastcgi_params;
      • }
    • location ~ /.(?!well-known).* {
      • deny all;
      • }
    • }
  • 启用站点并重启：
    • sudo ln -s /etc/nginx/sites-available/laravel.test /etc/nginx/sites-enabled/
    • sudo nginx -t && sudo systemctl reload nginx
• 本机 hosts（如访问域名）：echo “127.0.0.1 laravel.test” | sudo tee -a /etc/hosts
• Apache 方案（可选）：
  • sudo apt install -y apache2 libapache2-mod-php8.2
  • sudo a2enmod rewrite
  • 将虚拟主机 DocumentRoot 指向 /var/www/my-laravel-app/public，并配置 允许 AllowOverride All。

四 权限与常见排错

• 目录权限（推荐最小权限）：
  • sudo chown -R www-data:www-data /var/www/my-laravel-app
  • sudo chmod -R 755 /var/www/my-laravel-app
  • sudo chmod -R 775 storage bootstrap/cache（开发环境可用 777，生产请改为更安全的 775 并配合 ACL/组权限）
• 常见问题速查：
  • 502 Bad Gateway：检查 PHP-FPM 是否运行（systemctl status php8.2-fpm），以及 Nginx 中 fastcgi_pass 的 socket 路径是否与 /var/run/php/php8.2-fpm.sock 一致
  • 路由 404：确认 Nginx 配置包含 try_files $uri $uri/ /index.php?$query_string; 且站点根目录指向 public
  • 权限被拒：确认 storage、bootstrap/cache 对 www-data 可写
  • .env 未生效：执行 php artisan config:clear 后再访问
  • Composer 权限：全局安装时确保 ~/.composer/vendor/bin 在 PATH 中

五 开发环境优化与可选组件

• 启用 OPcache（提升性能，编辑 /etc/php/8.2/fpm/php.ini）：
  • opcache.enable=1
  • opcache.memory_consumption=128
  • opcache.interned_strings_buffer=8
  • opcache.max_accelerated_files=4000
  • opcache.revalidate_freq=60
  • opcache.fast_shutdown=1
  • 重启：sudo systemctl restart php8.2-fpm
• 路由与配置缓存（仅生产或稳定迭代时使用）：
  • php artisan route:cache
  • php artisan config:cache
• 前端资源（可选，Laravel Mix）：
  • 安装 Node.js（示例）：curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - && sudo apt-get install -y nodejs
  • npm install && npm run dev（或 npm run build）
• 队列与缓存（可选，提升体验）：
  • 安装 Redis：sudo apt install -y redis-server
  • .env：CACHE_DRIVER=redis；QUEUE_CONNECTION=redis
  • 启动队列：php artisan queue:work --tries=3