PHP框架部署需依次完成环境配置、文件上传、Web服务器设置、依赖安装、权限调整及错误排查：先确认PHP版本与扩展，再上传项目并指向public目录，接着运行composer install与密钥生成，然后设置storage等目录权限及SELinux策略，最后通过日志定位500错误。
如果您已开发完成一个PHP框架项目，但不知道如何将其部署到服务器上运行，则可能是由于缺乏对服务器环境配置、文件上传和权限设置等环节的了解。以下是针对新手的完整部署流程与常见问题处理步骤：
一、准备服务器环境
PHP框架项目依赖特定版本的PHP、Web服务器（如Nginx或Apache）以及扩展组件（如PDO、cURL、mbstring等），需先确认并安装匹配的基础环境。不同框架对PHP版本有明确要求，例如Laravel 10需要PHP 8.1+，ThinkPHP 8要求PHP 8.0+。
1、登录服务器，执行 php -v 检查当前PHP版本是否符合框架要求。
2、若版本不符，使用包管理器升级PHP：Ubuntu系统执行 sudo apt install php8.1 php8.1-cli php8.1-mysql php8.1-curl php8.1-mbstring php8.1-xml php8.1-zip。
立即学习“PHP免费学习笔记（深入）”；
3、验证扩展是否启用：运行 php -m | grep -E "pdo|curl|mbstring"，确保关键扩展出现在输出中。
二、上传项目文件至服务器
将本地开发完成的PHP框架项目完整传输至服务器指定目录（如 /var/www/myapp），需注意保留目录结构与隐藏文件（如 .env、.gitignore）。
1、使用SCP命令上传：在本地终端执行 scp -r ./myapp/ user@server_ip:/var/www/。
2、若使用FTP工具（如FileZilla），选择SFTP协议连接，以root或具有写入权限的用户登录，将项目拖入目标路径。
3、上传完成后，在服务器中执行 ls -la /var/www/myapp/，确认 .env、public/、vendor/ 等关键目录存在。
三、配置Web服务器指向public目录
多数现代PHP框架（如Laravel、ThinkPHP）采用前端控制器模式，入口文件位于 public/index.php，Web服务器必须将根目录设为此处，而非项目根目录，否则路由和资源将无法正确加载。
1、对于Nginx，编辑站点配置文件（如 /etc/nginx/sites-available/myapp），将 root 指向 /var/www/myapp/public。
2、在server块内添加PHP处理规则，确保包含 fastcgi_pass unix:/run/php/php8.1-fpm.sock; 及对应 include snippets/fastcgi-php.conf;。
3、测试配置并重载：执行 sudo nginx -t && sudo systemctl reload nginx。
四、安装依赖与生成运行时文件
框架项目通常不提交 vendor/ 目录，需在服务器上通过Composer安装依赖；部分框架还需生成缓存、密钥或配置优化文件，否则访问时会报错或性能低下。
1、进入项目根目录：执行 cd /var/www/myapp。
2、安装依赖：运行 composer install --no-dev --optimize-autoloader（生产环境禁用开发依赖）。
3、生成应用密钥（以Laravel为例）：执行 php artisan key:generate；ThinkPHP则需确保 runtime/ 目录可写，并执行 php think optimize:config。
五、设置目录权限与SELinux状态
Web服务器进程（如www-data或nginx用户）需对日志、缓存、上传等目录具备读写权限；若服务器启用了SELinux（常见于CentOS/RHEL），默认策略可能阻止PHP脚本写入指定路径，导致500错误或空白页。
1、设置storage与bootstrap/cache可写：执行 sudo chown -R www-data:www-data storage bootstrap/cache（Ubuntu/Debian）或 sudo chown -R nginx:nginx storage bootstrap/cache（CentOS/RHEL）。
2、修改权限：运行 sudo chmod -R 755 storage bootstrap/cache。
3、检查SELinux状态：执行 sestatus，若为enabled，临时放行HTTPD写入：运行 sudo setsebool -P httpd_can_network_connect 1 和 sudo setsebool -P httpd_read_user_content 1。
六、排查常见500错误原因
部署后访问首页返回500错误，通常由PHP解析失败、配置缺失或权限不足引起，需逐层定位。日志是核心依据，优先查看Web服务器错误日志与PHP错误日志。
1、查看Nginx错误日志：执行 sudo tail -f /var/log/nginx/error.log，刷新网页观察实时报错内容。
2、开启PHP错误显示（仅调试阶段）：编辑 /etc/php/8.1/fpm/php.ini，将 display_errors = On 和 error_reporting = E_ALL，然后重启PHP-FPM：sudo systemctl restart php8.1-fpm。
3、检查 .env 文件是否存在且格式正确：运行 ls -l /var/www/myapp/.env 并确认其内容无语法错误（如未闭合引号、多余空格）。
