01-环境搭建与项目初始化
<![CDATA[# 第1章 环境搭建与项目初始化
## 1.1 开发环境要求
### 必备组件
| 组件 | 最低版本 | 推荐版本 | 说明 |
| ------ | ------------------------------ | -------------------- | -------------------------------- |
| Web服务器 | Apache 2.4+ / Nginx 1.14+ | Nginx | 需支持URL重写 |
| PHP | 7.2 | 8.0+ | 需开启pdo\_mysql/gd/mbstring/json扩展 |
| MySQL | 5.6 | 5.7+ / MariaDB 10.2+ | InnoDB引擎 |
| PHP扩展 | pdo\_mysql, gd, mbstring, json | 同左 | XiunoPHP核心依赖 |
### 推荐开发工具
- **Laragon** (Windows首选): 轻量级，支持快速切换PHP/MySQL版本，自动配置虚拟主机
- **XAMPP**: 一键安装，适合初学者
- **VS Code**: 推装扩展 - PHP Intelephense、PHP Debug、Bootstrap 5 Snippets
### 不支持的环境
- Docker: Xiuno BBS的文件锁机制和tmp目录编译缓存与容器化环境存在兼容问题
- IIS: URL重写规则不兼容
## 1.2 安装Xiuno BBS开发环境
### 步骤1: 下载源码
将Xiuno BBS源码放置到Web根目录，如 `M:\laragon\www\xxiunobbs\`。
### 步骤2: 配置Web服务器
**Nginx伪静态规则**:
```nginx
location / {
if (!-e $request_filename) {
rewrite ^/(.*)$ /index.php?$1 last;
}
}
```
**Apache伪静态规则** (项目自带`.htaccess`):
```apache
<IfModule mod_rewrite.c>
RewriteEngine on
RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^(.*)$ index.php?$1 [QSA,PT,L]
</IfModule>
```
### 步骤3: 开启DEBUG模式
编辑 `index.php`，将DEBUG常量设为2:
```php
define('DEBUG', 2);
```
DEBUG级别说明:
- `0`: 生产模式，不显示错误，使用压缩版xiunophp.min.php，tmp缓存永久有效
- `1`: 调试模式，显示错误，使用完整版xiunophp.php，tmp缓存永久有效
- `2`: 开发模式，显示错误，使用完整版xiunophp.php，**每次请求重新编译tmp缓存**
> **关键**: 插件开发必须使用 `DEBUG=2`，否则hook/overwrite的修改不会立即生效。上线前务必改回 `0`。
### 步骤4: 配置数据库
安装向导会自动生成 `conf/conf.php`，包含数据库连接信息和缓存配置。
### 步骤5: 配置php.ini
```ini
display_errors = On
error_reporting = E_ALL
upload_max_filesize = 20M
post_max_size = 20M
```
## 1.3 项目目录结构
```
xxiunobbs/
├── index.php # 入口文件（DEBUG在此设置）
├── conf/
│ └── conf.php # 系统配置（数据库/缓存/URL等）
├── xiunophp/ # XiunoPHP框架核心
│ ├── db_mysql.class.php
│ ├── db_pdo_mysql.class.php
│ ├── cache_apc.class.php
│ ├── cache_redis.class.php
│ ├── cache_memcached.class.php
│ └── misc.func.php # 全局工具函数
├── model/ # 核心Model层
│ ├── plugin.func.php # ★ 插件系统核心（_include/hook/overwrite）
│ ├── kv.func.php # 键值存储
│ ├── cache.func.php # 缓存管理
│ ├── thread.func.php # 主题模型
│ ├── post.func.php # 帖子模型
│ ├── user.func.php # 用户模型
│ ├── forum.func.php # 版块模型
│ ├── group.func.php # 用户组模型
│ └── ...
├── model.inc.php # Model加载入口（含hook: model_inc_file.php）
├── index.inc.php # 路由分发入口（含大量hook点）
├── route/ # 核心路由文件
│ ├── index.php # 首页
│ ├── forum.php # 版块
│ ├── thread.php # 主题
│ ├── post.php # 帖子
│ ├── user.php # 用户
│ ├── my.php # 个人中心
│ └── ...
├── view/
│ └── htm/ # 核心模板文件
│ ├── header.inc.htm
│ ├── footer.inc.htm
│ ├── index.htm
│ ├── forum.htm
│ ├── thread.htm
│ ├── post.htm
│ └── ...
├── admin/ # 后台管理
│ ├── route/
│ │ └── plugin.php # 插件管理路由
│ └── view/
│ └── htm/
├── plugin/ # ★ 插件目录
│ ├── xn_search/ # 搜索插件
│ ├── xn_tag/ # 标签插件
│ ├── tt_sign/ # 签到插件
│ └── ...
├── tmp/ # 编译缓存目录（自动生成）
├── upload/ # 上传文件目录
└── lang/ # 语言包
├── zh-cn.php
└── en-us.php
```
## 1.4 请求生命周期
理解请求从进入到响应的完整路径，是插件开发的基础:
```
用户请求 → index.php
├─ 加载 conf/conf.php
├─ 加载 xiunophp 核心（DEBUG>1加载完整版，否则压缩版）
├─ 数据库连接（懒加载，首次查询时才连接）
├─ 加载 model/plugin.func.php（插件系统初始化）
├─ _include(model.inc.php) → 编译合并 → tmp/model.inc.php
│ └─ hook: model_inc_file.php（插件注入model文件）
├─ _include(index.inc.php) → 编译合并 → tmp/index.inc.php
│ ├─ 启动会话
│ ├─ 加载语言包
│ ├─ 读取当前用户信息
│ ├─ 获取版块列表
│ ├─ hook: index_route_case_start.php
│ ├─ 路由分发: param(0) → switch-case → route/xxx.php
│ ├─ hook: index_route_case_end.php（插件注册新路由）
│ └─ hook: index_inc_end.php
└─ 输出HTML/JSON
```
## 1.5 开发工作流
```
1. 创建插件目录和conf.json
2. 编写install.php（建表/初始化配置）
3. 编写hook文件（注入逻辑到系统）
4. 编写route文件（处理请求）
5. 编写view文件（页面展示）
6. 编写setting.php + setting.htm（配置页面）
7. 编写unstall.php（清理数据）
8. 测试: 安装→启用→功能测试→卸载→重装
9. DEBUG=0生产环境验证
```
]]>