# 开发环境搭建

<cite>
**本文引用的文件**
- [composer.json](file://composer.json)
- [README.md](file://README.md)
- [public/index.php](file://public/index.php)
- [public/api.php](file://public/api.php)
- [public/router.php](file://public/router.php)
- [.example.env](file://.example.env)
- [public/.htaccess](file://public/.htaccess)
- [public/upload/.htaccess](file://public/upload/.htaccess)
- [public/themes/.htaccess](file://public/themes/.htaccess)
- [public/themes/.htaccess_apache2.4](file://public/themes/.htaccess_apache2.4)
- [public/plugins/swagger/composer.lock](file://public/plugins/swagger/composer.lock)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本指南面向 ThinkCMF 的本地开发环境搭建，覆盖系统要求与环境配置、Composer 依赖管理、Web 服务器（Apache/Nginx）配置、IDE 推荐配置、开发工具链（Xdebug、Git、数据库客户端）以及常见问题排查。ThinkCMF 基于 ThinkPHP 8.x，采用多应用架构与 Composer 管理依赖，入口文件位于 public 目录并通过 URL 重写实现“美化”URL。

## 项目结构
- 入口文件：public/index.php（前台）、public/api.php（API）
- URL 重写：public/.htaccess（Apache）
- 路由适配：public/router.php（兼容场景）
- 环境配置：.example.env（示例环境变量）
- 插件与扩展：public/plugins/*（如 Swagger 插件）

```mermaid
graph TB
A["浏览器"] --> B["Web 服务器<br/>Apache/Nginx"]
B --> C["public/.htaccess<br/>URL 重写规则"]
C --> D["public/index.php<br/>前台入口"]
C --> E["public/api.php<br/>API 入口"]
D --> F["vendor/autoload.php<br/>Composer 自动加载"]
E --> F
F --> G["框架内核与应用<br/>App()->http 运行"]
```

图表来源
- [public/.htaccess:1-15](file://public/.htaccess#L1-L15)
- [public/index.php:1-37](file://public/index.php#L1-L37)
- [public/api.php:1-41](file://public/api.php#L1-L41)

章节来源
- [public/index.php:1-37](file://public/index.php#L1-L37)
- [public/api.php:1-41](file://public/api.php#L1-L41)
- [public/router.php:1-20](file://public/router.php#L1-L20)
- [public/.htaccess:1-15](file://public/.htaccess#L1-L15)

## 核心组件
- PHP 版本与扩展
  - 最低要求：PHP 8.1+
  - 必需扩展：json、curl、pdo、mbstring、zip
- 数据库支持
  - MySQL 5.7+、MariaDB 10.2+
- Composer 依赖
  - 通过 composer.json 声明依赖与自动加载规则
  - 提供 post-autoload-dump 脚本，自动执行服务发现、发布资源与迁移
- 环境变量
  - 使用 .env 控制调试等参数；示例文件为 .example.env

章节来源
- [composer.json:30-42](file://composer.json#L30-L42)
- [composer.json:67-72](file://composer.json#L67-L72)
- [README.md:90-94](file://README.md#L90-L94)
- [.example.env:1-1](file://.example.env#L1-L1)

## 架构总览
ThinkCMF 的请求从 Web 服务器进入，经 URL 重写后交由入口文件（index.php 或 api.php）加载 Composer 自动加载器，随后由框架内核执行 HTTP 应用并返回响应。

```mermaid
sequenceDiagram
participant U as "用户代理"
participant S as "Web 服务器"
participant R as "public/.htaccess"
participant I as "public/index.php"
participant A as "public/api.php"
participant L as "vendor/autoload.php"
participant K as "框架内核"
U->>S : 请求 / 或 /api/...
S->>R : 匹配重写规则
alt 访问 /api/...
R-->>A : 转发到 api.php
A->>L : 加载自动加载器
L-->>K : 初始化框架
K-->>U : 返回响应
else 访问 /
R-->>I : 转发到 index.php
I->>L : 加载自动加载器
L-->>K : 初始化框架
K-->>U : 返回响应
end
```

图表来源
- [public/.htaccess:1-15](file://public/.htaccess#L1-L15)
- [public/index.php:1-37](file://public/index.php#L1-L37)
- [public/api.php:1-41](file://public/api.php#L1-L41)

## 详细组件分析

### 系统要求与环境配置
- PHP 版本
  - 最低要求：PHP 8.1
  - 推荐：PHP 8.2（以获得更好的性能与稳定性）
- 必需扩展
  - json、curl、pdo、mbstring、zip
- 数据库
  - MySQL 5.7+、MariaDB 10.2+
- URL 重写
  - Apache：启用 mod_rewrite 并使用 public/.htaccess
  - Nginx：需自行配置 rewrite 规则，将未命中文件的请求转发至 public/index.php 或 public/api.php
- 目录权限
  - public 目录作为站点根目录
  - data、upload 等目录需具备写权限（按部署策略调整）
- 环境变量
  - 参考 .example.env 设置 .env，包含调试开关、时区、数据库连接等

章节来源
- [README.md:84-94](file://README.md#L84-L94)
- [composer.json:30-42](file://composer.json#L30-L42)
- [.example.env:1-1](file://.example.env#L1-L1)

### Composer 依赖管理
- 安装与配置
  - 在项目根目录执行安装，生成 vendor/
  - 自动加载 PSR-4/PSR-0 映射，支持 app、api、plugins、themes 命名空间
- 依赖生命周期
  - 安装完成后执行 post-autoload-dump 脚本：
    - 服务发现
    - 发布资源
    - 执行迁移
- 常用命令
  - 安装：composer install
  - 更新：composer update
  - 优化：composer dump-autoload --optimize

```mermaid
flowchart TD
Start(["开始"]) --> Install["执行 composer install/update"]
Install --> Scripts["触发 post-autoload-dump 脚本"]
Scripts --> Discover["service:discover"]
Scripts --> Publish["vendor:publish"]
Scripts --> Migrate["migrate:run"]
Discover --> End(["完成"])
Publish --> End
Migrate --> End
```

图表来源
- [composer.json:67-72](file://composer.json#L67-L72)

章节来源
- [composer.json:46-56](file://composer.json#L46-L56)
- [composer.json:60-66](file://composer.json#L60-L66)
- [composer.json:67-72](file://composer.json#L67-L72)

### Web 服务器配置（Apache/Nginx）
- Apache
  - 启用 mod_rewrite
  - 将站点根目录指向 public/
  - 使用 public/.htaccess 实现重写规则，将 /api/... 转发到 api.php，其他请求转发到 index.php
  - 目录访问控制：public/upload 与 public/themes 目录包含 .htaccess 限制直接访问
- Nginx
  - 需手动配置 rewrite 规则，将未匹配文件的请求转发到 public/index.php 或 public/api.php
  - 示例要点：location ~ ^/(?!api|index.php) { try_files /index.php$is_args$args; }（具体以实际需求为准）
- 目录权限
  - public 目录对外可读
  - data、upload 等目录需具备写权限（按部署策略调整）

```mermaid
flowchart TD
A["Apache"] --> B["站点根目录指向 public/"]
B --> C["启用 mod_rewrite"]
C --> D["应用 .htaccess 重写规则"]
D --> E["/api/... -> api.php"]
D --> F["其他 -> index.php"]
A2["Nginx"] --> B2["站点根目录指向 public/"]
B2 --> C2["配置 try_files 或 rewrite"]
C2 --> F2["转发到 index.php 或 api.php"]
```

图表来源
- [public/.htaccess:1-15](file://public/.htaccess#L1-L15)
- [public/upload/.htaccess:1-4](file://public/upload/.htaccess#L1-L4)
- [public/themes/.htaccess:1-4](file://public/themes/.htaccess#L1-L4)
- [public/themes/.htaccess_apache2.4:1-3](file://public/themes/.htaccess_apache2.4#L1-L3)

章节来源
- [public/.htaccess:1-15](file://public/.htaccess#L1-L15)
- [public/upload/.htaccess:1-4](file://public/upload/.htaccess#L1-L4)
- [public/themes/.htaccess:1-4](file://public/themes/.htaccess#L1-L4)
- [public/themes/.htaccess_apache2.4:1-3](file://public/themes/.htaccess_apache2.4#L1-L3)

### IDE 配置建议（PhpStorm/VS Code）
- 通用建议
  - PHP 版本：选择 8.1+（推荐 8.2）
  - 代码风格：遵循 PSR-12
  - 自动加载：确保 Composer 自动加载已生成
- PhpStorm
  - PHP 路径映射：将远程路径映射到本地工作目录
  - 代码检查：开启 PHPDoc、命名空间、PSR 规范检查
  - 运行配置：使用内置 Web 服务器或配置 Apache/Nginx
- VS Code
  - 扩展：PHP Intelephense、PHP Sniffer、EditorConfig、PHP CS Fixer
  - 设置：启用 PHP 语言服务器、自动格式化、保存时修复

### 开发工具链
- Xdebug 调试
  - 安装与启用 Xdebug 扩展
  - 在 IDE 中配置断点与监听端口
  - 通过 GET 参数或 Cookie 触发调试会话
- Git 版本控制
  - 初始化仓库：git init
  - 添加忽略文件：.gitignore 已包含常见忽略项
  - 推送远程仓库（如 Gitee/GitHub）
- 数据库客户端
  - 推荐：phpMyAdmin、DBeaver、Navicat
  - 连接参数：根据 .env 或数据库配置文件填写主机、端口、用户名、密码、字符集

## 依赖分析
- 关键依赖
  - thinkcmf/cmf-app、cmf-install、cmf-api、cmf-appstore、cmf-root
- 插件生态
  - Swagger 插件依赖 Doctrine Annotations 等包，其 composer.lock 展示了 PHP 版本与扩展要求（如 php >= 8.1）

```mermaid
graph LR
Root["composer.json"] --> App["thinkcmf/cmf-app"]
Root --> Install["thinkcmf/cmf-install"]
Root --> API["thinkcmf/cmf-api"]
Root --> Store["thinkcmf/cmf-appstore"]
Root --> RootPkg["thinkcmf/cmf-root"]
Swagger["Swagger 插件"] --> Doctrine["doctrine/annotations"]
```

图表来源
- [composer.json:37-41](file://composer.json#L37-L41)
- [public/plugins/swagger/composer.lock:10-34](file://public/plugins/swagger/composer.lock#L10-L34)

章节来源
- [composer.json:30-42](file://composer.json#L30-L42)
- [public/plugins/swagger/composer.lock:10-34](file://public/plugins/swagger/composer.lock#L10-L34)

## 性能考虑
- 启用 OPcache（生产环境）
- 使用 Composer 优化自动加载（dump-autoload --optimize）
- 合理配置数据库连接池与查询缓存
- 静态资源 CDN 与压缩（按项目配置）

## 故障排查指南
- 无法访问 /api
  - 检查 Apache 是否启用 mod_rewrite，确认 public/.htaccess 存在且规则正确
  - 确认站点根目录指向 public/
- 404 或重定向循环
  - 确保 public/.htaccess 中的 RewriteCond 与 RewriteRule 正确
  - Nginx 需自行配置 try_files 或 rewrite
- 权限问题
  - data、upload 等目录需具备写权限
  - public/themes 与 public/upload 的 .htaccess 限制了直接访问，属正常安全措施
- PHP 版本或扩展缺失
  - 确认 PHP >= 8.1，并已启用 json、curl、pdo、mbstring、zip
- 环境变量未生效
  - 复制 .example.env 为 .env，并按需修改数据库与调试参数

章节来源
- [public/.htaccess:1-15](file://public/.htaccess#L1-L15)
- [public/upload/.htaccess:1-4](file://public/upload/.htaccess#L1-L4)
- [public/themes/.htaccess:1-4](file://public/themes/.htaccess#L1-L4)
- [composer.json:30-42](file://composer.json#L30-L42)
- [.example.env:1-1](file://.example.env#L1-L1)

## 结论
按照本指南完成系统要求、Composer 依赖、Web 服务器与 IDE/工具链配置后，即可在本地顺利运行与开发 ThinkCMF 项目。遇到问题时，优先检查 PHP 版本与扩展、URL 重写规则、目录权限与 .env 配置。

## 附录
- 入口文件与运行流程参考
  - [public/index.php:1-37](file://public/index.php#L1-L37)
  - [public/api.php:1-41](file://public/api.php#L1-L41)
  - [public/router.php:1-20](file://public/router.php#L1-L20)
- 环境与依赖参考
  - [composer.json:30-42](file://composer.json#L30-L42)
  - [README.md:84-94](file://README.md#L84-L94)
  - [.example.env:1-1](file://.example.env#L1-L1)