Xiuno 安装失败全攻略：常见坑与快速自救指南

52JinY 助手

这两天帮朋友在一台闲置的轻量云装 Xiuno，踩了几轮坑，整理一份排查笔记，给后来人省点时间。场景是典型的 LEMP/LAMP 小环境：Nginx 或 Apache，PHP7.x/8.x，MySQL/MariaDB。问题表象五花八门：安装界面空白、安装停在第二步、提示数据库连接失败、后台白屏、附件上传报错等。往往不是 Xiuno 本身的问题，而是环境细节不匹配。

先说致命级的三件事。第一，PHP 版本与扩展。Xiuno 对 PHP8 以上某些语法和废弃函数不完全兼容，尤其是 8.1/8.2 上常见的 Deprecated/Warning 会变成致命错误，导致白屏。我的经验是优先用 PHP7.2-7.4，确保开启 pdo_mysql、mbstring、json、gd、openssl、zlib、curl。缺哪个在安装页就容易卡死或报奇怪错。第二，目录权限。upload、tmp、log、data 这类目录需要可写（一般 0755/0775 即可，不建议上来就 777），Nginx/Apache 运行用户要对这些目录有写权限，否则安装写配置失败、附件无法上传、缓存不生成。第三，数据库编码与权限。创建数据库时统一 utf8mb4 和 utf8mb4_unicode_ci，账户要有建表/索引权限。有些商家面板默认 utf8，中文+表情会出问题。

再说 Web 服务器的细节。用 Nginx 的同学，rewrite 必须正确。Xiuno 依赖 index.php 路由，常见配置是 location / { try_files $uri $uri/ /index.php?$query_string; }，同时给静态资源单独 location，避免 php 拦截。忘了 try_files 就会出现访问首页正常、点进帖子 404 的现象。Apache 则要确保 AllowOverride 开启，让 .htaccess 生效；不开的话伪静态形同虚设。另一个隐蔽点是 fastcgi_param PATH_INFO 的传递，有的面板模板删了这行，路由就不对。

如果你遇到安装页空白或 500，别慌，先打开错误日志。Nginx 看 error.log，Apache 看 error_log，PHP 单独的 error_log 也要开。很多主机默认关闭 display_errors，页面不会显示任何信息，但日志里能直接告诉你是哪个函数、哪个扩展报错。Xiuno 本身也有 log 目录，安装后可以在 conf 调高调试级别，定位插件或模板的报错来源。

关于文件来源，尽量用官方发布包或可信镜像，避免一些“改良版”带私货。上传时注意二进制模式、完整性校验，尤其是通过 FTP 上传，丢文件或权限错位很常见。若你是从 Windows 压缩后传到 Linux，再解压，留意换行符和权限继承问题。

数据库连接失败的排查顺序可以标准化：用命令行 mysql -h host -u user -p 先验证账号是否能连；确认端口不是被安全组/防火墙挡住；确认本地用 127.0.0.1 而不是 localhost（有时 socket 配置不同导致连不上）；确认数据库名、前缀没有特殊字符；最后看 sql_mode，过于严格（如 ONLY_FULL_GROUP_BY）可能在安装建表或统计查询时报错，必要时在 my.cnf 降一降。

安装成功但后台白屏，大多是 PHP8 的兼容问题或插件模板冲突。做法是先关插件：直接在数据库里把插件表里的启用字段置 0；切回默认主题；清空 cache（data/tmp 或 runtime 缓存）；再看错误日志定位具体文件。升级 PHP 版本前，先在测试环境跑一遍，别在线上“热升级”。

附件上传失败通常是三件套：php.ini 的 upload_max_filesize、post_max_size 太小；Nginx 的 client_max_body_size 没跟上；以及目录权限/所属用户不一致。三者对齐到一个合理值，比如 10M 或 20M，问题多半解决。头像裁剪失败还可能是 GD 或 exif 扩展未装。

最后给一套最省心的流程：准备干净环境（PHP7.4 + pdo_mysql/mbstring/gd/openssl 等 + MySQL5.7/ MariaDB10.3+），创建 utf8mb4 数据库；按官方示例写好 Nginx/Apache rewrite；解压到站点根目录，确保写权限；浏览器访问安装向导；安装后立刻调低权限、关闭 display_errors，打开日志；再逐个安装主题/插件，每装一个就刷新看日志，出问题好回滚。

很多时候，解决速度取决于你能否第一时间看到“真正的报错”。别怕看日志，别急着 777，一步步排除，Xiuno 其实挺皮实的。