【避坑记录】Z-BlogPHP 1.7.5 主题导出 zba 报 500,以及迁移过程中踩到的 5 个坑 意见建议 Bug反馈 二次开发

用户 NeilNiu 11小时前 33


> 环境:Z-BlogPHP 1.7.5 / PHP 8.2(**未装 mbstring**)/ Windows + open_basedir / nginx + PHP-FPM
> 场景:把 WordPress 站点迁移到 Z-BlogPHP,自建主题、打包 zba、上线部署。
> 下面全部是实测踩坑 + 已验证的修法,不改核心文件。

坑 1(重点):开启开发者模式后,主题页面点「导出应用」直接 HTTP 500

现象

后台 → 应用中心 → 启用开发者模式 → 主题管理 → 点「导出应用」,浏览器直接 500。

关掉开发者模式、重启 PHP、换主题都无效。服务器错误日志里是这一类提示:

Warning: is_dir(): open_basedir restriction in effect.
File(./zb_users/theme/xxx/*.code-workspace) is not within the allowed path(s)


排查过程

1. 先排除常见项:目录权限、PHP 执行时间、`memory_limit`、`upload_max_filesize` —— 都正常,而且只是「导出」这一个动作报错。
2. 定位到核心文件 `zb_system/lib/app.php` 里的 `App::Pack()`。
3. 发现它遍历 `$app->ignore_files` 时,把列表里的**通配符条目**(例如 `*.code-workspace`)当成真实路径传给了 `is_dir()`:

// 伪代码,示意
foreach ($app->ignore_files as $file) {
    if (is_dir($app->path . $file)) {   // <-- $file = '*.code-workspace'
        ...
    }
}


在 Windows + `open_basedir` 下,`*` 是字面字符,不是合法路径,于是 `is_dir()` 抛出 open_basedir 限制,整个请求 500。
Linux 上很多时候只是返回 false 不报错,所以这个坑**在 Windows 环境更容易复现**。

修复:用官方 hook 剔除通配符,不改核心

Z-BlogPHP 在 `App::Pack()` 执行前会触发 `Filter_Plugin_App_Pack`,可以把参数 `$app`、`$dirs`、`$files` 引用传进来改。
在**主题自己的 `include.php`** 里加下面这段即可:

<?php
/**
 * 修复 Z-BlogPHP 1.7.5 「导出应用」在 Windows + open_basedir 下 HTTP 500
 * 原因:App::Pack() 把 ignore_files 中的通配符(如 *.code-workspace)
 *       原样传给 is_dir(),触发 open_basedir 限制。
 * 处理:打包前过滤掉含 * ? [ 的通配符条目,保留普通文件名。
 * 说明:通过官方 Filter_Plugin_App_Pack 钩子实现,不修改任何核心文件。
 */
if (!function_exists('my_fix_pack_ignore')) {
    function my_fix_pack_ignore(&$app, &$dirs, &$files)
    {
        if (empty($app->ignore_files) || !is_array($app->ignore_files)) {
            return null;
        }
        $keep = array();
        foreach ($app->ignore_files as $v) {
            if (strpos($v, '*') === false
                && strpos($v, '?') === false
                && strpos($v, '[') === false) {
                $keep[] = $v;
            }
        }
        $app->ignore_files = $keep;
        return null;
    }
}
if (!isset($GLOBALS['hooks']['Filter_Plugin_App_Pack']['my_fix_pack_ignore'])) {
    $GLOBALS['hooks']['Filter_Plugin_App_Pack']['my_fix_pack_ignore'] = 0;
}


把文件保存到 `zb_users/theme/你的主题/include.php`(已有 include.php 的就追加进去),刷新后台,再点「导出应用」,就能正常下载 zba 了。

注意点:

- 主题的 `include.php` 在后台也会被加载,所以钩子能生效;不要写成只有前台才 include 的形式。
- 函数名换成自己主题前缀,避免和别人冲突。
- 这只影响导出时的忽略列表,**不影响主题功能**,也不改核心,升级 Z-Blog 后依然有效。
- 如果以后官方修了这个 bug,这段钩子留着也无害(它只是过滤掉本来就不该存在的通配符)。

如何验证导出包是好的

导出的 zba 不是 ZIP,别用压缩软件打开。它是一个 **gzip 压缩的 XML**:

解压看内容

gzip -dc mytheme.zba | head -c 500

正常应该看到:

xml
<?xml version="1.0" encoding="utf-8"?>
<app version="php" type="theme">
  <id>...</id>
  <name>...</name>
  ...
  <file><path>主题ID/template/index.php</path><stream>Base64...</stream></file>
</app>

能读出 `<app type="theme">` 和一堆 `<file>`,说明包是合法的。

坑 2:以为 zba 是 ZIP,用压缩软件改包结果越改越坏

zba 的真实格式:

| 项 | 实际 |
|---|---|
| 容器 | `gzip(XML)` |
| 根节点 | `<app version="php" type="theme">` |
| 文件存放 | `<file><path>ID/相对路径</path><stream>Base64</stream></file>` |
| 目录声明 | `<folder><path>ID/目录</path></folder>` |
| 校验区 | `<verify></verify>` |

直接从 ZIP 思路去「替换一个文件」是不行的。要么走官方导出,要么按上面的 XML 结构重新构造包。

 坑 3:包做出来了,上传却失败

后台上传提示失败、无详细报错,先看这两个 php.ini 项:

ini
upload_max_filesize = 2M     ; 很多虚拟主机默认就 2M
post_max_size        = 8M


主题里如果有大图、字体、视频,很容易超。处理顺序建议:

1. 图片压到 WebP / 适当降分辨率,字体只留用到的字重;
2. 实在要传大包,临时把 `ZC_UPLOAD_FILESIZE` 调大(**上传完一定改回去**);
3. 上传后逐文件核对是否真正落地,别只看「上传成功」提示。

另外后台上传接口需要带 `token`、`csrfToken` 和正确的 `Referer`,文件字段名是 `edtFileLoad`。用脚本模拟上传时少一个都会失败。

坑 4:部分文章卡片摘要不显示,但正文里明明有摘要

现象

列表页有的卡片有摘要,有的空白。

根因(两个叠加)

1. 服务器 **没有 mbstring 扩展**,主题里用了 `substr()` 按**字节**截中文,把一个 UTF-8 汉字从中间切断,产生非法字节序列;
2. 随后 `htmlspecialchars()` 遇到非法 UTF-8 直接返回空字符串 —— 于是摘要整段消失。

如果用了 `preg_replace('/\s+/u', ...)` 这类带 `/u` 的正则,遇到非法 UTF-8 还会返回 `null`,又是一次「整段清空」。

修复:按字符截断 + ENT_SUBSTITUTE 兜底

php
function rh_e($s)
{
    // ENT_SUBSTITUTE:遇到非法字节用替代字符,而不是返回空
    return htmlspecialchars((string) $s, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8');
}
function rh_text($html, $len = 100)
{
    $s = strip_tags((string) $html);
    $collapsed = preg_replace('/\s+/u', ' ', $s);
    // /u 正则失败会返回 null,绝不能让 null 覆盖原字符串
    $s = ($collapsed === null) ? $s : $collapsed;
    $s = trim(html_entity_decode($s, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8'));
    if ($s === '') {
        return '';
    }
    if (function_exists('mb_substr')) {
        return mb_substr($s, 0, $len, 'UTF-8')
            . (mb_strlen($s, 'UTF-8') > $len ? '…' : '');
    }
    // 没有 mbstring:按「字符」切,不会把汉字劈开
    if (preg_match_all('/./us', $s, $m) && !empty($m[0])) {
        $chars = $m[0];
        return implode('', array_slice($chars, 0, $len))
            . (count($chars) > $len ? '…' : '');
    }
    // 最后兜底:按字节切后回退到合法 UTF-8 边界
    $cut = substr($s, 0, $len * 3);
    while ($cut !== '' && preg_match('//u', $cut) !== 1) {
        $cut = substr($cut, 0, -1);
    }
    return $cut . (strlen($s) > $len * 3 ? '…' : '');
}


一句话经验:中文站的主题,永远不要用 `substr()` 直接截正文。

 坑 5:独立页面(Page)用 GetArticleList() 永远取不到

 现象

主题里写了个「取所有独立页做导航/列表」的函数,用的是 `GetArticleList()`,结果一直空的,页面全回退到首页链接。

原因

Z-BlogPHP 的 `GetArticleList()` 内部写死了 `log_Type = 0`,只返回**文章**;独立页面是 `log_Type = 1`,要用 `GetPageList()`。

 修复

php
function my_pages($limit = 20)
{
    global $zbp;
    try {
        $w = array(array('=', 'log_Status', 0));
        // 关键:用 GetPageList(),它才是 log_Type = 1
        $r = $zbp->GetPageList(
            array('*'),
            $w,
            array('log_PostTime' => 'DESC'),
            array((int) $limit),
            null
        );
        return is_array($r) ? array_values($r) : array();
    } catch (Throwable $e) {
        return array();
    }
}


 坑 6:做了品牌化 404 页面,线上却还是 nginx 的裸 404
 现象

本地/部分环境能看到主题 404 页,正式服务器上访问已删除内容,显示的是:


404 Not Found
nginx



把中间件信息暴露出来了,也很难看。

原因

nginx 开了 `fastcgi_intercept_errors on`。PHP 返回 404 时,nginx 会**丢弃 PHP 的输出**,替换成自己的错误页。主题模板再漂亮也没机会显示。

 修复:模板里先把状态码改成 200

在主题的 `template/404.php` 最前面:

smarty
{* Template Name:404页面 * Template Type:404 *}
{php}
if (!headers_sent()) {
    header_remove('Status');
    header_remove('X-Powered-By');
    header_remove('Product');
    http_response_code(200);
    // 不希望这个页被搜索引擎收录
    header('X-Robots-Tag: noindex, nofollow', true);
}
{/php}
{template:header}
...你的品牌化 404 内容...
{template:footer}


`http_response_code(200)` 让 nginx 不再拦截,PHP 的 HTML 就能正常输出;再用 `X-Robots-Tag: noindex, nofollow` 告诉搜索引擎别收录这个友好像。

**更规范的做法**是在 nginx 侧关掉 `fastcgi_intercept_errors` 或配置 `error_page 404 = /404.php`,但很多共享主机不给改配置,上面这种主题内解法更通用。

配合前端 5 秒倒计时回首页:

js
(function () {
    var num = document.getElementById('rhCountdownNum');
    var btn = document.getElementById('rhCancelRedirect');
    if (!num) return;
    var left = 5;
    var timer = setInterval(function () {
        left--;
        num.textContent = left;
        if (left <= 0) { clearInterval(timer); location.href = '/'; }
    }, 1000);
    function cancel() { clearInterval(timer); }
    if (btn) btn.addEventListener('click', cancel);
    document.addEventListener('click', function (e) {
        if (e.target.closest('a')) cancel();
    });
})();


 附:官方导出(开发者模式)的正确姿势

规避上面坑 1 之后,流程其实很简单:

1. 后台 → 应用中心 → 开启开发者模式;
2. 主题管理页 → 在主题上点「导出应用」;
3. 浏览器下载得到 `.zba`;
4. 按「坑 2」的方法 `gzip -dc` 检查包内文件是否齐全;
5. 在另一套环境上传验证。

这比手工拼 XML + Base64 + gzip 靠谱得多,**建议优先用官方导出**,只有在官方导出确实没法用(例如核心 bug 且不能加钩子)时才考虑手工打包。


一张表总结

| # | 坑 | 一句话解法 |
|---|---|---|
| 1 | 开发者模式导出 500 | `Filter_Plugin_App_Pack` 钩子过滤 `ignore_files` 里的通配符 |
| 2 | 把 zba 当 ZIP | 它是 gzip(XML),文件是 Base64 |
| 3 | 上传失败 | 查 `upload_max_filesize`,压素材,带 token/csrfToken/Referer 上传 |
| 4 | 摘要空白 | 禁用 `substr` 截中文,按字符切 + `ENT_SUBSTITUTE` |
| 5 | 独立页取不到 | 用 `GetPageList()`,不是 `GetArticleList()` |
| 6 | 404 变 nginx 裸页 | 模板里 `http_response_code(200)` + `noindex` |

希望这篇能帮到同样在迁移/打包主题的朋友。有更优雅的解法欢迎在楼下补充。

最后于 11小时前 被NeilNiu编辑 ,原因:
最新回复 (0)
全部楼主
    • Z-Blog 开发者社区
      2 楼
        丨  
返回