简介

本指南面向首次参与 DouPHP 项目的开发者，目标是帮助你在最短时间内完成本地开发环境的搭建与调试。内容涵盖：

• 服务器环境要求（PHP、MySQL、Web 服务器）
• 完整的环境安装步骤（含伪静态配置）
• IDE 配置建议（PHPStorm、VS Code）
• Git 仓库克隆与分支管理策略
• 快速启动方法（XAMPP/WAMP/Laragon/Docker 思路）
• 配置文件说明（数据库连接、应用密钥、路径与安全）
• 常见问题排查与解决方案

项目结构

DouPHP 采用“三端入口 + 共享核心 + 模块化”的架构：

• 前台 front：访客与会员使用的 HTML 渲染入口
• 后台 admin：管理员使用的 HTML 渲染入口
• API api：JSON 接口，供小程序/SPA/第三方调用
• core：框架核心（容器、ORM、安全、通用服务）
• config：站点配置（数据库、模块清单、路由、安全等）
• storage：运行时存储（缓存、日志、备份、临时文件）
• theme/miniprogram/plugin/languages：主题、小程序源码、插件、多语言包

graph TB
A["浏览器"] --> B["Web 服务器<br/>Apache/Nginx"]
B --> C["根入口 index.php"]
C --> D["核心引导 core/bootstrap.php"]
D --> E["配置加载 config/*.php"]
D --> F["自动加载与门面注册"]
D --> G["请求对象 Request 单例"]
C --> H["路由分发 Route::dispatch()"]
H --> I["前端控制器/服务层"]
I --> J["数据库/文件系统/缓存"]

核心组件

• 入口与引导
  • 根入口 index.php 负责设置路由委托、解析语言前缀、执行 Init 引导并调度路由。
  • 核心引导 core/bootstrap.php 进行 PHP 版本检测、定义常量、加载配置、注册自动加载、初始化 DI 容器与 Request 单例。
• 配置中心
  • config/config.php：数据库连接、表前缀、字符集、系统标识、目录别名、应用密钥、调试开关。
  • config/security.php：可信代理/Host、安全响应头、限流、会话 Cookie 硬化。
  • config/route.php：URL 重写风格规则（页面/栏目/简单模块）。
  • config/module.php：模块清单与关联标记。
• 路由与中间件
  • .htaccess：Apache 伪静态规则，统一将 URL 改写为各端入口并透传 route 参数。
  • 三端各自的路由与中间件在对应目录下组织。

架构总览

下图展示了从 Web 服务器到业务处理的请求链路，以及关键配置的作用点。

sequenceDiagram
participant U as "用户浏览器"
participant W as "Web 服务器(Apache/Nginx)"
participant R as "根入口 index.php"
participant B as "核心引导 bootstrap.php"
participant C as "配置中心 config/*"
participant RT as "路由分发 Route"
participant S as "服务/控制器"
participant DB as "数据库"
U->>W : HTTP 请求
W->>R : 转发至 index.php?route=...
R->>B : require core/bootstrap.php
B->>C : 读取数据库/安全/路由/模块配置
B-->>R : 返回已就绪的容器与 Request
R->>RT : 设置委托并 dispatch()
RT->>S : 匹配路由并调用控制器/服务
S->>DB : 读写数据
S-->>RT : 返回响应
RT-->>W : 发送响应
W-->>U : 返回页面或 JSON

详细组件分析

服务器与环境要求

• PHP 版本：支持 5.6 – 8.x，建议 8.x。引导阶段会强制检查最低版本。
• MySQL：任意兼容版本；建议使用 5.7+。
• Web 服务器：Apache 或 Nginx，需启用 URL 重写。
• PHP 扩展：GD、PDO 或 mysqli、OpenSSL；Apache 需 mod_rewrite。
• 编码：UTF-8 无 BOM。

安装与部署步骤

• 将源码部署到网站根目录。
• 访问首页，若未安装则自动跳转到安装程序 install/index.php。
• 按提示填写数据库信息、管理员账号，完成安装。
• 安装完成后会在 storage/install.lock 写入锁文件，再次访问不再进入安装流程。
• 如需重装，删除 storage/install.lock 后重新访问安装程序。

Web 服务器伪静态配置

• Apache：使用项目根目录的 .htaccess 实现 URL 重写，将 /api、/admin、前台路由统一改写为对应入口并携带 route 参数。
• Nginx：需在站点配置中实现等价的重写规则，确保静态资源不被误拦截，并将动态请求转发到对应入口。

配置文件说明

• 数据库连接与基础常量
  • 主机、库名、用户名、密码、表前缀、字符集、系统标识、目录别名、应用密钥、调试开关均在配置文件中定义。
• 安全配置
  • 可信代理与可信 Host 白名单、安全响应头、限流、会话 Cookie 硬化等。
• 路由风格
  • 提供多种 URL 风格规则（页面/栏目/简单模块），可按需覆盖。
• 模块清单
  • 栏目模块与简单模块列表，以及是否链接 AI、会员中心、工作台、订单等标记。

请求处理流程（代码级）

flowchart TD
Start(["请求到达"]) --> Boot["加载核心引导<br/>bootstrap.php"]
Boot --> CheckInstall{"是否已安装?"}
CheckInstall -- 否 --> RedirectInstall["重定向到安装程序"]
CheckInstall -- 是 --> LoadConfig["加载配置 config/*"]
LoadConfig --> Register["注册自动加载/门面/容器/Request"]
Register --> Dispatch["路由分发 Route::dispatch()"]
Dispatch --> Handler["控制器/服务处理"]
Handler --> Response["生成响应并发送"]
RedirectInstall --> End(["结束"])
Response --> End

错误处理与调试

• 未捕获异常：根据 site.debug 与请求类型输出调试页或 JSON 500，并记录错误日志。
• 业务异常：以统一的业务错误码与消息返回，便于前端友好展示。
• 调试开关：可通过配置控制开启/关闭调试模式。

依赖分析

• 运行期依赖
  • PHP 版本与扩展（GD、PDO/mysqli、OpenSSL）
  • Web 服务器 URL 重写能力
  • MySQL 数据库
• 配置依赖
  • 数据库连接信息、应用密钥、安全策略、路由风格、模块清单
• 内部依赖
  • 入口依赖核心引导；引导依赖配置；路由依赖 Request 与容器；控制器/服务依赖 ORM、文件系统、缓存等

graph LR
P["PHP 运行时"] --> E["扩展: GD/PDO/OpenSSL"]
S["Web 服务器"] --> R["URL 重写"]
R --> I["入口 index.php"]
I --> B["引导 bootstrap.php"]
B --> C["配置 config/*"]
B --> A["自动加载/门面/容器"]
A --> Q["Request 单例"]
I --> T["路由分发"]
T --> M["模块/控制器/服务"]
M --> DB["MySQL"]

性能注意事项

• 生产环境务必关闭调试模式，避免输出敏感信息与额外开销。
• 合理配置可信代理与 Host 白名单，防止 IP/Host 伪造带来的缓存投毒与外链污染。
• 对高频接口启用限流策略，避免恶意请求拖垮系统。
• 使用合适的 PHP 版本与 Web 服务器组合，开启 OPcache 与合适的 PHP-FPM 进程数。
• 图片等资源通过 CDN 或静态资源服务器托管，减轻后端压力。

故障排查指南

• 无法进入安装界面
  • 检查 storage/install.lock 是否存在；若存在且需要重装，请删除该文件后重试。
  • 确认 Web 服务器已启用 URL 重写，且 .htaccess 生效（Apache）或等效 Nginx 规则已配置。
• 数据库连接失败
  • 核对 config/config.php 中的数据库主机、库名、用户名、密码、表前缀是否正确。
  • 确认 MySQL 服务可访问，且用户权限正确。
• 页面 404 或路由不生效
  • 检查 .htaccess 是否被忽略（Apache 需 AllowOverride All），或 Nginx 重写规则是否正确。
  • 确认路由风格与 URL 格式一致，必要时调整 config/route.php。
• 安全相关报错
  • 若部署在反向代理之后，需在 config/security.php 中配置 trusted_proxies，否则 Request::ip() 可能不正确。
  • 若出现 Host 校验失败，配置 trusted_hosts 白名单。
• 调试与日志
  • 开启 DOU_DEBUG 后可获得更详细的错误信息；生产环境应关闭。
  • 查看 PHP 错误日志与系统日志定位问题。

结论

按照本指南完成环境准备、伪静态配置与基础配置后，即可在本地快速启动 DouPHP 并进行二次开发。建议在团队内统一 PHP 版本、IDE 配置与 Git 工作流，以减少环境差异带来的协作成本。

附录

IDE 配置建议

• PHPStorm
  • 解释器：选择与线上一致的 PHP 版本（推荐 8.x）
  • 代码规范：UTF-8 无 BOM、4 空格缩进、LF 换行
  • 自动加载：识别 PSR-4 与 ClassMap（由核心引导注册）
  • 调试：配置 Xdebug 并与 IDE 集成
  • 模板：启用对 .dwt/.htm 的语法高亮与跳转
• VS Code
  • 插件：PHP Intelephense、Docker、GitLens、Markdown All in One
  • 格式化：保存时按规则格式化（UTF-8、LF、4 空格）
  • 调试：配置 launch.json 使用 Xdebug
  • 终端：使用内置终端执行 Composer/脚本命令

Git 仓库克隆与分支管理

• 克隆仓库
  • 使用 HTTPS 或 SSH 克隆到本地工作目录
• 分支策略（建议）
  • main/master：稳定版本
  • develop：开发主干
  • feature/*：功能分支
  • hotfix/*：紧急修复分支
  • release/*：发布候选分支
• 提交规范
  • 简洁明了的提交信息，关联任务编号
  • 频繁小步提交，便于回滚与审查

快速启动方法

• 传统本地套件（XAMPP/WAMP/Laragon）
  • 将源码放入站点根目录，启用 Apache/Nginx 与 PHP，确保 .htaccess 生效
  • 访问首页进入安装流程
• Docker（概念性步骤）
  • 使用官方 php:8-fpm + nginx 镜像
  • 挂载源码目录，配置端口映射与环境变量
  • 编写 docker-compose.yml 编排服务，启动后访问首页进入安装流程

常见环境与配置项速查

• 数据库连接
  • 主机、库名、用户名、密码、表前缀、字符集
• 应用密钥
  • 用于签名与加密的应用密钥
• 路径与目录
  • 前台/后台/API/小程序目录别名
• 安全
  • 可信代理、可信 Host、安全响应头、限流、会话 Cookie 硬化
• 路由风格
  • 页面/栏目/简单模块的 URL 风格规则