拿到一份PHP项目源码之后，能不能顺利跑起来，主要取决于三件事：运行环境是否匹配、依赖是否装齐、配置文件是否改对。很多初学者以为把文件夹放进Web目录就能访问，结果出现空白页或者报错，其实就是忽略了PHP版本和扩展的差异。下面按实际部署顺序，把本地调试和生产环境运行的方法讲清楚。
一、拿到源码后先做什么
在动手部署前，先别急着复制文件。打开项目根目录，重点看几个地方：有没有composer.json文件，有没有.env或config.php之类的配置，以及有没有README或install.md说明。这些文件直接告诉你项目依赖哪些PHP扩展、用不用数据库、入口文件在哪里。
如果项目使用了Composer管理依赖，根目录一般会有vendor文件夹。若没有，就说明需要自己执行安装。另外注意public或web目录，很多现代PHP框架把入口文件index.php放在这里，Web服务器应该指向这个目录，而不是项目根目录，否则会暴露源码。
1.1 检查PHP版本与扩展
用命令行输入下面指令可查看当前PHP版本和已加载扩展：
php -v php -m
假设源码的composer.json里写明了"php": "^8.1"，而你本地是PHP 7.4，那就必须切换版本。常见必需扩展包括pdo_mysql、mbstring、openssl、gd等，缺一个都可能让项目启动失败。
二、本地环境快速部署
对新手最友好的方式是使用集成环境，例如phpStudy、XAMPP或者Docker。它们把PHP、Apache或Nginx、MySQL打包好，切换版本只需点几下。以phpStudy为例，创建网站时指定根目录为源码的public文件夹，选择对应PHP版本，工具会自动配置虚拟主机。
如果你更想理解底层，可以手动安装PHP和Nginx。下面是一段Ubuntu下用apt安装PHP与常用扩展的命令：
sudo apt update sudo apt install php8.1 php8.1-fpm php8.1-mysql php8.1-mbstring php8.1-gd nginx mysql-server
装好后，把源码放到/var/www/example，再配置Nginx站点。手动方式的优势是环境干净、可控，缺点是要自己处理权限和服务的启动问题。
2.1 使用Composer安装依赖
进到项目根目录，执行安装命令。若本地没装Composer，需先下载安装。
cd /var/www/example composer install
执行后vendor目录会出现。若报错内存不足，可加-d memory_limit=-1参数。依赖装完，项目才具备运行基础，很多函数调用都来自这些包。
三、配置与数据库初始化
大部分PHP项目通过配置文件连接数据库。以.env文件为例，你需要修改以下几项：
DB_HOST=127.0.0.1 DB_DATABASE=test_db DB_USERNAME=root DB_PASSWORD=123456
注意不要把真实密码写进版本库。改完配置，如果有database/migrations目录，通常要用命令行建表：
php artisan migrate
不是所有项目都用Laravel，有些老项目是直接提供sql文件，那就用MySQL客户端导入。无论哪种方式，先确认数据库用户有权限，否则页面会报连接拒绝。
3.1 Nginx站点配置示例
下面是一个最简化的Nginx配置，把域名指向public目录，并由PHP-FPM处理脚本：
server {
listen 80;
server_name example.local;
root /var/www/example/public;
index index.php;
location / {
try_files $uri $uri/ /index.php?$query_string;
}
location ~ .php$ {
include snippets/fastcgi-php.conf;
fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;
}
}
配置完执行nginx -t检测语法，再systemctl reload nginx。此时访问example.local就能看到项目首页。若仍报错，打开PHP错误显示，看日志定位。
四、常见运行问题与排查
部署中最常遇到的是五百错误和空白页。第一步应打开错误输出，在php.ini里设置display_errors = On，或是在入口文件顶部加：
<?php
error_reporting(E_ALL);
ini_set('display_errors', '1');
另一个坑是目录权限。框架需要写storage或runtime目录，若属主是root而PHP进程用户无权写入，就会失败。用chown改为www-data并给755通常能解决。
4.1 生产环境注意事项
上线时要关闭错误显示，配置好域名HTTPS，并把调试模式关掉。以Laravel为例，.env里APP_DEBUG=false。同时用Supervisor管理队列进程，避免PHP-FPM超时。生产环境建议用Docker Compose统一环境与版本，减少“本地能跑线上不行”的矛盾。
只要按环境匹配、依赖安装、配置修正、权限检查这四步推进，绝大多数PHP源码都能顺利部署运行。遇到特殊框架，优先查官方文档，思路是一致的。