centos与laravel集成开发环境搭建指南

CentOS 与 Laravel 集成开发环境搭建指南

一 环境准备与版本要求

• 操作系统：CentOS 7/8（本文以 yum/dnf 系为主，若为 CentOS Stream 亦可参考，命令基本一致）。
• Web 服务器：Nginx 或 Apache（二选一，下文分别给出配置要点）。
• PHP 版本：建议 PHP 8.1+（Laravel 10/11 要求 PHP ≥ 8.1；若使用旧版 Laravel 7/8，则至少 PHP 7.4）。
• 数据库：MySQL 8.0 或 MariaDB 10.3+。
• 必备扩展：php-cli php-fpm php-mysqlnd php-json php-gd php-mbstring php-xml php-bcmath php-curl php-zip fileinfo tokenizer openssl。
• 工具：Composer 2.x（PHP 依赖管理）。

二 安装与配置 Web 与 PHP

• 安装 EPEL 与 Remi 仓库（便于获取新版 PHP）：
  • sudo yum install -y epel-release
  • sudo yum install -y https://rpms.remirepo.net/enterprise/remi-release-7.rpm
  • sudo yum-config-manager --enable remi-php81 # 如需 PHP 8.1；其他版本按需启用
• 安装 PHP 与常用扩展（以 PHP 8.1 为例）：
  • sudo yum install -y php php-cli php-fpm php-mysqlnd php-json php-gd php-mbstring php-xml php-bcmath php-curl php-zip
• 安装并启动 Web 服务器（二选一）
  • Nginx：sudo yum install -y nginx && sudo systemctl enable --now nginx
  • Apache：sudo yum install -y httpd && sudo systemctl enable --now httpd
• 验证：php -v、php -m | grep -E ‘mbstring|gd|pdo_mysql|zip|bcmath|tokenizer|fileinfo|openssl’、nginx -t 或 httpd -t。

三 安装与配置数据库

• 安装数据库（二选一）
  • MySQL 8.0：sudo yum install -y mysql-server && sudo systemctl enable --now mysqld
  • MariaDB 10.3+：sudo yum install -y mariadb-server && sudo systemctl enable --now mariadb
• 安全初始化：sudo mysql_secure_installation（设置 root 密码、移除匿名用户、禁止远程 root 登录、删除测试库等）。
• 创建应用数据库与用户（示例）：
  • mysql -u root -p
  • CREATE DATABASE laravel_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
  • CREATE USER ‘laravel_user’@‘localhost’ IDENTIFIED BY ‘StrongPass!23’;
  • GRANT ALL PRIVILEGES ON laravel_db.* TO ‘laravel_user’@‘localhost’;
  • FLUSH PRIVILEGES;
  • EXIT;
• 注意：如为远程数据库，创建用户时使用 ‘%’ 主机并开放防火墙端口 3306。

四 安装 Composer 与创建 Laravel 项目

• 安装 Composer（全局可用）：
  • curl -sS https://getcomposer.org/installer | php
  • sudo mv composer.phar /usr/local/bin/composer
  • sudo chmod +x /usr/local/bin/composer
• 创建项目（推荐在 /var/www/ 下）：
  • cd /var/www
  • composer create-project --prefer-dist laravel/laravel my_laravel_app
• 目录权限（以 Web 服务运行用户为准，常见为 nginx 或 apache）：
  • sudo chown -R nginx:nginx /var/www/my_laravel_app
  • sudo chmod -R 755 /var/www/my_laravel_app/storage /var/www/my_laravel_app/bootstrap/cache
• 配置 .env（数据库部分示例）：
  • DB_CONNECTION=mysql
  • DB_HOST=127.0.0.1
  • DB_PORT=3306
  • DB_DATABASE=laravel_db
  • DB_USERNAME=laravel_user
  • DB_PASSWORD=StrongPass!23
• 生成应用密钥并测试迁移：
  • cd /var/www/my_laravel_app
  • php artisan key:generate
  • php artisan migrate --seed（如有迁移与种子数据）。

五 Web 服务器配置与常见问题

• Nginx 配置示例（/etc/nginx/conf.d/laravel.conf，root 指向 public）：
  • server { listen 80; server_name your_domain_or_IP; root /var/www/my_laravel_app/public; index index.php index.html; charset utf-8; location / { try_files $uri $uri/ /index.php?$query_string; } location ~ .php$ { fastcgi_pass unix:/run/php-fpm/www.sock; # 以实际 php-fpm 配置为准 fastcgi_index index.php; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; include fastcgi_params; } location ~ /.(?!well-known).* { deny all; } add_header X-Frame-Options “SAMEORIGIN”; add_header X-Content-Type-Options “nosniff”; }
  • 检查并重载：sudo nginx -t && sudo systemctl reload nginx
• Apache 虚拟主机示例（/etc/httpd/conf.d/laravel.conf）：
  • <VirtualHost *:80> ServerName your_domain_or_IP DocumentRoot /var/www/my_laravel_app/public <Directory /var/www/my_laravel_app/public> AllowOverride All Require all granted ErrorLog ${APACHE_LOG_DIR}/laravel_error.log CustomLog ${APACHE_LOG_DIR}/laravel_access.log combined
  • 启用重写模块：sudo a2enmod rewrite（Debian 系常见；CentOS 若使用 httpd，通常默认支持 .htaccess）
  • 检查并重载：sudo httpd -t && sudo systemctl reload httpd
• 常见问题与排查
  • 403/404：确认 DocumentRoot 指向 public，且目录 AllowOverride All 生效。
  • 白屏或 No input file specified：检查 fastcgi_param SCRIPT_FILENAME 是否为 $document_root$fastcgi_script_name，以及 php-fpm 监听地址与权限。
  • 权限错误：确保 storage、bootstrap/cache 对 Web 服务用户可写。
  • 数据库连接失败：核对 .env 中 DB_HOST/PORT/USER/PASS，确认数据库监听 127.0.0.1:3306 或 socket 可达。
  • 路由 404：确认 Nginx 的 try_files 规则或 Apache 的 mod_rewrite 已启用。
• 可选优化（生产环境建议按需开启）：
  • 配置 OPcache（/etc/php.d/opcache.ini）：opcache.enable=1、opcache.memory_consumption=128、opcache.interned_strings_buffer=8、opcache.max_accelerated_files=4000、opcache.validate_timestamps=0（开发环境设为 1 便于热更新）
  • Laravel 缓存：php artisan config:cache、php artisan route:cache、php artisan view:cache（开发环境不建议）。