从零跑通Xiuno BBS：目录结构、入口文件与本地调试环境搭建

如果你刚接触Xiuno BBS，面对一堆文件夹和PHP文件，可能第一反应是“我该改哪里”。这篇帖子不聊插件开发，也不谈模板美化，只解决一个问题：把项目跑起来，并搞清楚每个目录是干什么的。

一、先看整体目录，别急着改代码

下载源码解压后，你会看到这样几个核心目录：

• app/ —— 应用核心，包含控制器、模型和视图。日常二次开发主要动这里。
• conf/ —— 配置文件目录。conf.php是全局配置，重点看它。
• route/ —— 路由规则定义，URL如何映射到控制器，就是在这里约定的。
• view/ —— HTML模板文件，按模块分子目录，比如forum、user、admin。
• upload/ —— 附件上传目录，需要给写权限。
• plugin/ —— 插件存放处，每个子文件夹就是一个独立插件。

新手最容易踩的坑：把模板文件直接改在view里，却忽略缓存。Xiuno的模板是编译后运行的，改完不刷新缓存，页面永远不变。

二、入口文件index.php到底做了什么

所有请求都先经过根目录的index.php，它内部做了三件关键事：

1. 加载conf/conf.php里的配置项（数据库连接、调试开关等）。
2. 注册自动加载函数，让系统能按需加载类文件，不需要手动include。
3. 调用核心的bootstrap逻辑，解析当前URL，匹配路由，然后执行对应的控制器方法。

如果你想自定义入口逻辑，比如加一个环境判断，可以在index.php里动手，但建议只在本地调试时改，线上保持原样。

三、本地调试环境：用PHP内置服务器最快

很多人卡在“装不上Nginx/Apache”这一步，其实Xiuno支持PHP自带的开发服务器，两行命令就能跑起来：

cd 你的项目目录
php -S localhost:8888

然后浏览器访问http://localhost:8888即可。如果页面报错，先检查两个地方：

• upload目录是否可写（Linux下执行chmod -R 777 upload）。
• conf/conf.php里的数据库配置是否正确——本地建议用SQLite，省去装MySQL的麻烦。把db配置改成sqlite类型，指定一个文件路径即可。

四、新手调试的三个小技巧

第一，打开调试模式。在conf/conf.php里找到debug相关配置，设为true，页面底部会输出SQL查询和加载耗时，排查问题非常直观。

第二，善用日志。Xiuno的日志写在tmp/log目录下，如果页面白屏但没报错，去翻日志文件，往往能直接看到致命错误的具体行号。

第三，改完模板不生效？去tmp目录删除编译后的模板缓存文件，或者直接在后台“清除缓存”。记住这个步骤，能省下你半小时的困惑。

五、一个最小可运行的改动示例

想验证环境是否通顺，可以试着改首页标题。找到view/forum/index.htm（不同版本文件名可能有差异），把标签里的内容改掉，刷新页面看效果。如果没变化，去tmp目录清一下缓存再刷新，基本就成了。

这条路走通之后，再往深了学路由和控制器，就不会觉得Xiuno是个黑盒了。