本地开发环境搭建 - 开发学习教程

"在我电脑上能跑啊"——这是开发圈最著名的借口。环境不一致是无数诡异 bug 的根源：本地 PHP 8.1，服务器 PHP 7.4；本地开了某扩展，服务器没开。要消灭这类问题，第一步是规范搭建本地开发环境。本篇以建站最常用的 PHP + Nginx + MySQL 组合为例，讲清环境搭建的每个关键点，让本地环境与生产环境保持一致。

一、环境套件选择与安装

手动逐个装 PHP、Nginx、MySQL 既繁琐又容易出问题，新手建议用集成套件。macOS 推荐 Laragon 或 DDEV，Windows 推荐 Laravel Herd 或 PhpStudy，Linux 直接用包管理器。套件的好处是一键装齐所有组件，版本切换方便。但要注意套件自带的版本是否与生产服务器一致——开发环境的核心原则是"与生产对齐"。

# macOS 用 Homebrew 安装独立组件（推荐，灵活可控）
brew install nginx mysql@8.0 php@8.1 node

# 启动服务
brew services start nginx
brew services start mysql@8.0
brew services start php@8.1

# 验证版本（务必与生产服务器对齐）
php -v       # PHP 8.1.x
nginx -v     # nginx/1.25.x
mysql --version  # mysql  Ver 8.0.x

# 检查 PHP 必备扩展
php -m | grep -E 'pdo_mysql|mbstring|openssl|curl|gd|redis'
# 缺失扩展用 pecl 或 brew 安装
brew install php8.1-redis  # 或 pecl install redis

尧图团队统一要求 PHP 8.1+、MySQL 8.0、Nginx 1.22+，并在 composer.json 里声明最低 PHP 版本约束："php": ">=8.1"。这样低版本环境会直接报错，避免运行时出现兼容性问题。扩展方面，pdo_mysql、mbstring、openssl、curl、gd 是建站必备，缺一不可。

二、Nginx 虚拟主机配置

本地开发要把 http://ldpk.local 指向本地项目，而不是用 http://localhost/ldpk.cn 这种子目录形式——子目录路径会让静态资源引用、路由配置跟生产不一致，埋下隐患。做法是配置 Nginx 虚拟主机 + 修改 hosts 文件。

# Nginx 虚拟主机配置：/usr/local/etc/nginx/servers/ldpk.conf
server {
    listen 80;
    server_name ldpk.local;           # 本地域名
    root /Users/yourname/projects/ldpk.cn/public;  # 站点根目录（指向public）
    index index.php index.html;

    # 访问日志（调试时很有用）
    access_log /usr/local/var/log/nginx/ldpk.access.log;
    error_log  /usr/local/var/log/nginx/ldpk.error.log;

    location / {
        # 伪静态：不存在的文件转给 index.php
        try_files $uri $uri/ /index.php?$query_string;
    }

    # PHP 文件交给 PHP-FPM 处理
    location ~ \.php$ {
        fastcgi_pass 127.0.0.1:9000;   # PHP-FPM 监听地址
        fastcgi_index index.php;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    }

    # 静态资源不记日志，提升性能
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff2?)$ {
        access_log off;
        expires 1h;
    }

    # 禁止访问隐藏文件（.git、.env 等）
    location ~ /\. {
        deny all;
    }
}

# 修改 hosts 文件（/etc/hosts），把本地域名指向本机
127.0.0.1  ldpk.local

# 重载 Nginx 配置
nginx -s reload

# 现在 http://ldpk.local 就能访问本地项目了

一个常见坑：fastcgi_pass 地址要对上 PHP-FPM 实际监听的地址，Homebrew 装的 PHP-FPM 默认监听 127.0.0.1:9000，但有的套件用 unix socket。配置不对会报 502 Bad Gateway。尧图建议本地开发就开 display_errors = On，让 PHP 错误直接显示在页面，方便调试；生产环境务必关闭。

三、Composer 与项目依赖

PHP 项目的依赖管理靠 Composer——它相当于 Node 的 npm、Python 的 pip。composer.json 声明依赖，composer.lock 锁定确切版本。克隆项目后第一件事永远是 composer install，它会按 lock 文件安装一模一样版本的包，保证团队所有人依赖一致。

# 安装 Composer（macOS）
brew install composer

# composer.json 示例
{
  "require": {
    "php": ">=8.1",
    "ext-pdo": "*",
    "ext-mbstring": "*",
    "illuminate/database": "^10.0",    # ORM
    "league/route": "^5.1",            # 路由
    "twig/twig": "^3.5",               # 模板引擎
    "monolog/monolog": "^3.0"          # 日志
  },
  "require-dev": {
    "phpunit/phpunit": "^10.0",        # 单元测试
    "squizlabs/php_codesniffer": "^3.7" # 代码规范检查
  },
  "autoload": {
    "psr-4": { "App\\": "app/" }       # 自动加载映射
  },
  "config": {
    "optimize-autoloader": true
  }
}

# 常用命令
composer install          # 按 lock 文件安装依赖（克隆项目后执行）
composer update           # 更新依赖到最新版本（慎用，会改 lock）
composer require 包名     # 新增依赖
composer dump-autoload    # 重建自动加载（新增类后执行）

# 优化自动加载（生产环境必做，提升性能）
composer install --no-dev --optimize-autoloader

重点区分两个命令：install 严格按 lock 文件装，保证一致；update 会去解析最新版本并改写 lock 文件，可能引入不兼容更新。尧图规定：日常开发只用 install，需要升级依赖时由专人在分支上 update 并完整测试后再合并。另外 .env 配置文件不能提交到 Git（含数据库密码等敏感信息），只提交 .env.example 模板，每个人本地复制一份改自己的配置。这套规范能让新成员入职后 10 分钟内跑起项目，环境问题从此不再是拦路虎。