# 本地跑不起来？从零搭建 Xiuno BBS 调试环境的四步清单

很多新手拿到 Xiuno BBS 源码后，第一步就卡住了：文件放进 web 目录，浏览器打开却是空白，或者报一串看不懂的 PHP 错误。问题往往不在代码本身，而在环境没配对。这篇教程不讲架构原理，只做一件事——帮你把本地调试环境从零跑通。

先明确一个前提：Xiuno BBS 是一套轻量级 PHP 论坛程序，依赖 PHP + MySQL，不需要额外框架。这意味着环境配置的门槛不高，但几个关键参数必须对齐。

第一步：确认 PHP 版本与扩展

Xiuno 对 PHP 版本比较宽容，PHP 7.x 通常没问题，但有几个扩展必须打开：pdo_mysql、mbstring、gd、json。检查方法很简单，在 web 目录下建一个 info.php，内容写 ``，浏览器访问后搜索这几个扩展名。缺哪个就在 php.ini 里把前面的分号去掉，重启服务。

这里有个容易忽略的点：如果你用的是集成环境（如 phpStudy、XAMPP），切换 PHP 版本后要确认扩展是否跟着生效，不同版本的 php.ini 是独立的。

第二步：建库、导数据、改配置

在 MySQL 里新建一个库，字符集选 utf8mb4。然后把源码包里 install 目录下的 SQL 文件导入。接下来找到配置文件，通常在 conf/conf.php 或类似路径，把数据库地址、库名、用户名、密码填进去。如果安装时没有生成配置文件，可以手动复制一份示例文件改名。

这一步最常见的报错是“数据库连接失败”。先别怀疑代码，用命令行或 Navicat 单独连一次数据库，确认账号密码和端口没问题，再回头看配置文件里的引号和转义。

第三步：处理目录权限与入口路径

Xiuno 需要往 upload、tmp、log 这类目录写文件。Linux 或 macOS 下把目录权限设为 755、文件 644，必要时给 web 用户写权限。Windows 下一般不用管，但如果遇到“无法写入缓存”，检查目录是不是被设成了只读。

入口文件通常是 index.php，放在 web 根目录。如果你把源码放在子目录里，访问地址要带上子目录名。伪静态没配好时，先关掉伪静态，用 index.php?xxx 的形式访问，确认基础功能正常再折腾 rewrite 规则。

第四步：打开调试开关，让错误说出来

白屏最让人抓狂，因为没有任何信息。解决办法是让 PHP 把错误显示出来。在入口文件顶部临时加上：

`ini_set('display_errors', 1); error_reporting(E_ALL);`

同时确认 php.ini 里 display_errors 为 On。这样刷新页面后，具体的错误文件和行号就会直接显示。定位到问题后，记得把 display_errors 关掉，避免线上暴露路径信息。

另外建议开一个单独的日志文件，把 error_log 指向可写路径，这样即使页面不显示错误，也能从日志里翻到线索。

四步走完，大部分“本地跑不起来”的问题都能定位。环境配置没有太多技巧，关键是每一步都验证过再进入下一步，别跳步。你在搭建 Xiuno 环境时遇到过哪种报错？是数据库连不上，还是权限被拒？欢迎在评论区留下具体信息，一起看看卡在哪一环。