# 快速开始

<cite>
**本文引用的文件**
- [README.md](file://README.md)
- [composer.json](file://composer.json)
- [.example.env](file://.example.env)
- [public/index.php](file://public/index.php)
- [public/api.php](file://public/api.php)
- [public/router.php](file://public/router.php)
- [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)
- [vendor/autoload.php](file://vendor/autoload.php)
- [.gitignore](file://.gitignore)
- [AGENTS.MD](file://AGENTS.MD)
</cite>

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

## 简介
本指南面向首次接触 ThinkCMF 的开发者，帮助你在最短时间内完成环境准备、安装与配置，并理解多应用架构的入口文件作用与项目结构。ThinkCMF 基于 ThinkPHP 8.1，采用多应用架构，支持前台与 API 双入口，具备插件机制、多模板、RESTful API、Swagger 文档等能力。

## 项目结构
- 根目录包含应用、API、插件、主题、数据与公共资源等模块。
- 公共入口位于 public 目录，通过 index.php 进入前台应用，通过 api.php 进入 API 应用。
- Web 根目录应指向 public，配合 .htaccess 实现 URL 重写与路由分发。

```mermaid
graph TB
Root["项目根目录"]
Public["public<br/>Web 根目录"]
Index["index.php<br/>前台入口"]
Api["api.php<br/>API 入口"]
Router["router.php<br/>二次分发"]
Htaccess["public/.htaccess<br/>重写规则"]
Upload["public/upload<br/>上传目录"]
Themes["public/themes<br/>主题资源"]
Root --> Public
Public --> Index
Public --> Api
Public --> Router
Public --> Htaccess
Public --> Upload
Public --> Themes
```

图表来源
- [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)

章节来源
- [README.md:96-101](file://README.md#L96-L101)
- [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 版本：最低 8.1；推荐 8.2
  - 数据库：MySQL 5.5+（推荐 5.7+）
  - Web 服务器：Apache 或 Nginx（需开启 rewrite）
  - 必需 PHP 扩展：json、curl、pdo、mbstring、zip
- Composer 依赖与自动加载
  - composer.json 中声明了 ThinkCMF 核心包与命名空间映射
  - vendor/autoload.php 提供 Composer 自动加载入口
- 环境变量
  - 使用 .env 管理应用配置，支持数据库、时区、调试等参数
  - .example.env 提供示例键位，建议复制为 .env 并按需修改

章节来源
- [README.md:84-94](file://README.md#L84-L94)
- [composer.json:30-56](file://composer.json#L30-L56)
- [vendor/autoload.php:1-26](file://vendor/autoload.php#L1-L26)
- [.example.env:1-1](file://.example.env#L1-L1)
- [AGENTS.MD:718-741](file://AGENTS.MD#L718-L741)

## 架构总览
ThinkCMF 采用多应用架构，入口文件分别指向不同应用命名空间：
- public/index.php：前台应用入口，定义 APP_NAMESPACE 为 app
- public/api.php：API 应用入口，定义 APP_NAMESPACE 为 api
- public/.htaccess：将 /api 前缀与非文件请求转发至对应入口
- public/router.php：当静态资源不存在时，回退到 index.php

```mermaid
sequenceDiagram
participant Client as "浏览器"
participant Apache as "Web 服务器"
participant Htaccess as "public/.htaccess"
participant Router as "public/router.php"
participant Index as "public/index.php"
participant Api as "public/api.php"
Client->>Apache : 请求 / 或 /any-path
Apache->>Htaccess : 匹配重写规则
Htaccess->>Router : 若非静态文件则进入 router.php
Router->>Index : 回退到 index.php
Index-->>Client : 返回前台页面
Client->>Apache : 请求 /api/...
Apache->>Htaccess : 匹配 api 前缀
Htaccess->>Api : 转发到 api.php
Api-->>Client : 返回 API 响应
```

图表来源
- [public/.htaccess:1-15](file://public/.htaccess#L1-L15)
- [public/router.php:1-20](file://public/router.php#L1-L20)
- [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
  - 定义 CMF_ROOT、CMF_DATA、APP_PATH、WEB_ROOT
  - 加载 vendor/autoload.php
  - 通过 new App()->http 执行 HTTP 应用并响应
- public/api.php
  - 与 index.php 类似，但额外定义 APP_NAMESPACE 为 api
  - 用于 API 应用的请求处理

```mermaid
flowchart TD
Start(["请求到达"]) --> CheckAPI["是否以 /api 开头?"]
CheckAPI --> |是| ApiEntry["进入 api.php"]
CheckAPI --> |否| IndexEntry["进入 index.php"]
ApiEntry --> AutoLoad["加载 vendor/autoload.php"]
IndexEntry --> AutoLoad
AutoLoad --> RunApp["执行 App()->http->run()"]
RunApp --> SendResp["发送响应并结束"]
```

图表来源
- [public/api.php:1-41](file://public/api.php#L1-L41)
- [public/index.php:1-37](file://public/index.php#L1-L37)
- [vendor/autoload.php:1-26](file://vendor/autoload.php#L1-L26)

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

### URL 重写与路由分发
- public/.htaccess
  - 将 /api 前缀请求转发到 api.php
  - 将其他非文件请求转发到 index.php
  - 设置 Authorization 环境变量以兼容 API 认证
- public/router.php
  - 当请求不是真实文件时，回退到 index.php，避免直接暴露底层实现

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

### 目录权限与安全
- 目录权限
  - 生产环境建议设置 data 与 public/upload 目录可写（例如 777），便于安装与上传
- 安全配置
  - public/upload/.htaccess：禁止 html/php/json 直接访问
  - public/themes/.htaccess 与 public/themes/.htaccess_apache2.4：拒绝目录内敏感文件访问
  - .gitignore：排除 .env、config、docker 数据目录等敏感或临时文件

章节来源
- [AGENTS.MD:764-768](file://AGENTS.MD#L764-L768)
- [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)
- [.gitignore:1-17](file://.gitignore#L1-L17)

### 安装与配置流程
- 步骤概览
  1) 准备环境：PHP 8.1+、MySQL 5.5+、Apache/Nginx（开启 rewrite）
  2) 下载代码并安装依赖：composer install（生产环境可用 --no-dev 优化）
  3) 复制 .example.env 为 .env，填写数据库等配置
  4) 设置 Web 根目录为 public
  5) 给予 data 与 public/upload 目录写权限
  6) 访问站点进行安装（如需）
- 注意事项
  - .env 优先级高于动态配置与静态配置
  - 生产环境请关闭调试（APP_DEBUG=false）

章节来源
- [README.md:84-94](file://README.md#L84-L94)
- [composer.json:74-76](file://composer.json#L74-L76)
- [.example.env:1-1](file://.example.env#L1-L1)
- [AGENTS.MD:754-768](file://AGENTS.MD#L754-L768)
- [AGENTS.MD:737-741](file://AGENTS.MD#L737-L741)

### 第一个简单示例：创建基本内容页面
- 前台页面
  - 在前台应用中，通过 index.php 进入 app 命名空间
  - 页面模板通常位于 public/themes/default 或其他主题目录
  - 可参考默认主题的页面模板结构进行开发
- API 接口
  - 通过 /api 前缀访问 api.php，进入 api 命名空间
  - 可基于 RESTful 设计，结合 Swagger 插件生成接口文档
- 建议路径
  - 前台页面模板：public/themes/default/portal/page.html
  - API 控制器：api/controller/...（命名空间为 api）

章节来源
- [public/index.php:28-30](file://public/index.php#L28-L30)
- [public/api.php:28-33](file://public/api.php#L28-L33)
- [README.md:103-113](file://README.md#L103-L113)

## 依赖分析
- Composer 依赖
  - thinkcmf/cmf-app、cmf-api、cmf-install、cmf-appstore、cmf-root
  - PSR-4 映射 app\ → app、api\ → api、plugins\ → public/plugins、themes\ → public/themes
- 自动加载
  - vendor/autoload.php 提供 Composer 自动加载器初始化
- 安装脚本
  - post-autoload-dump 阶段执行 service:discover、vendor:publish、migrate:run

```mermaid
graph LR
Composer["composer.json<br/>依赖与脚本"] --> Vendor["vendor/<br/>自动加载"]
Vendor --> Autoload["vendor/autoload.php"]
Autoload --> App["App()->http->run()"]
```

图表来源
- [composer.json:30-76](file://composer.json#L30-L76)
- [vendor/autoload.php:1-26](file://vendor/autoload.php#L1-L26)

章节来源
- [composer.json:30-76](file://composer.json#L30-L76)
- [vendor/autoload.php:1-26](file://vendor/autoload.php#L1-L26)

## 性能考虑
- 生产环境建议
  - 使用 composer install --no-dev --optimize-autoloader
  - 关闭调试（APP_DEBUG=false）
  - 启用 OPcache、APCu 等加速扩展（由服务器配置决定）
- 目录权限
  - data 与 public/upload 目录保持可写，以便安装与上传
- CDN 与静态资源
  - 可将 public/static、public/themes 等静态资源接入 CDN

章节来源
- [AGENTS.MD:754-758](file://AGENTS.MD#L754-L758)
- [AGENTS.MD:764-768](file://AGENTS.MD#L764-L768)

## 故障排查指南
- 访问出现 404 或重定向异常
  - 确认 Web 根目录已指向 public
  - 检查 .htaccess 是否生效（Apache 需允许 .htaccess）
  - 确认 /api 前缀与非文件请求已正确转发
- 无法加载 API 或返回空白
  - 检查 api.php 是否被正确访问（/api/...）
  - 确认 APP_NAMESPACE 已定义为 api
- 安装或上传失败
  - 检查 data 与 public/upload 目录权限（建议 777）
  - 确认 .env 数据库配置正确
- 环境版本不满足
  - PHP 版本需 ≥ 8.1；Composer 版本过低会导致自动加载异常
- 安全相关
  - 确保 public/upload、public/themes 等目录存在 .htaccess 限制
  - .env 不要提交到版本控制（已在 .gitignore 中排除）

章节来源
- [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)
- [.gitignore:1-17](file://.gitignore#L1-L17)
- [vendor/autoload.php:5-21](file://vendor/autoload.php#L5-L21)

## 结论
通过本指南，你已经了解 ThinkCMF 的环境要求、多应用入口、URL 重写与路由分发、目录权限与安全策略、安装与配置流程，并掌握了创建第一个内容页面与 API 接口的基本思路。建议在开发过程中遵循生产环境最佳实践，逐步引入插件、主题与 Swagger 文档，提升开发效率与维护性。

## 附录
- 环境变量与配置优先级
  - .env（最高）→ data/config（动态）→ config（静态）
- 常用路径参考
  - 前台入口：public/index.php
  - API 入口：public/api.php
  - 重写规则：public/.htaccess
  - 上传目录：public/upload
  - 主题目录：public/themes

章节来源
- [AGENTS.MD:737-741](file://AGENTS.MD#L737-L741)
- [public/index.php:1-37](file://public/index.php#L1-L37)
- [public/api.php:1-41](file://public/api.php#L1-L41)
- [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)