精华 干货 XIUNOX 插件兼容性扫描器

概述

插件兼容性扫描器用于检测已安装插件中与 XIUNOX 现代化改造不兼容的代码，涵盖 PHP 8.0+ 语法、Bootstrap 5 迁移、jQuery 去除、安全规范等方面。

入口：后台 → 插件管理 → 插件兼容性检查（/*****/?plugin-scanner.htm）

相关文件

使用方式

1. 进入后台「插件兼容性检查」页面

2. 点击「开始扫描」按钮

3. 前端通过 fetch() 请求 ?plugin-scanner-do.htm，后端返回 JSON 格式扫描结果

4. 结果按插件分组展示，支持按严重级别筛选

5. 可导出 CSV 报告

扫描范围

扫描 plugin/ 目录下所有包含 conf.json 的插件目录，递归检查以下扩展名的文件：

• .php — PHP 代码

• .htm / .html — 模板文件

• .js — JavaScript 脚本

• .css — 样式文件

自动跳过 img/、images/、fonts/、vendor/、node_modules/ 等目录。

为避免误报，扫描器会将 .htm/.php/.html 文件中的 <script>/<style> 块与 PHP/HTML 部分分离：

• PHP-only 规则只扫描 PHP/HTML 部分，不会误扫 <script> 中的 JS 代码

• HTML-only 规则只扫描 PHP/HTML 部分，不会扫描纯 .php 文件

规则类别

严重级别说明

PHP 兼容性规则

废弃函数（PHP 7.x 移除）— fatal

检测 mysql_* 系列函数及其他在 PHP 7.x 已移除的函数：

PHP 8 不兼容语法 — fatal

花括号数组访问 — fatal

HTTP_*_VARS 变量 — fatal

PHP 8.0+ 废弃函数 — fatal

PHP 注释陷阱检测 — fatal

仅扫描 .php 文件。PHP 解析器会把单行注释中的 ?> 识别为 PHP 代码块结束标签，导致后续代码被当作纯文本输出。建议：移除注释中的 <?php 和 ?>，改用块注释 /* */。

HEREDOC 语法检测 — fatal

仅扫描 .php 文件。HEREDOC 语法中需使用 {$variable} 语法嵌入 PHP 变量，避免使用 <?php echo ... ?> 导致解析错误。

Service 类 SQL 未定义变量检测 — fatal

仅扫描 model/ 目录下 PHP 文件。Service 类中拼接 SQL 表名必须用 $this->tablepre . '表名'，不能使用未定义变量（如 $tableName、$tablePrefix）。

APP_PATH 误用检测 — fatal

仅扫描 .htm/.html 文件。APP_PATH 是文件系统绝对路径，浏览器无法访问，必须用 $conf['view_url'] 生成资源 URL。

Hook 文件头检测

检测 hook/*.* 文件的首行内容。.htm 模板 hook 文件会被编译拼进模板执行，以 <?php exit; 开头会白屏；.php 源码 hook 文件建议以 <?php exit; 开头防止直接访问。

安全规则

危险函数 — warning

权限安全（敏感字段修改）— warning

POST 表单缺少 CSRF 令牌 — warning

此规则采用文件级检测：读取整个文件内容，检查是否同时包含 method="post" 和 CsrfService/csrf_token，若缺少则报告。

前端 MD5 哈希检测 — warning

密码必须明文提交，由服务端 password_md5() 处理。前端 MD5 哈希已移除，MD5.js 不得全局加载。

MD5.js 全局加载检测 — warning

仅扫描 .htm/.html 文件。MD5.js 不得全局加载，前端 MD5 哈希已移除。

user_update 修改密码检测 — warning

找回密码必须使用 user__update() 而非 user_update()，因为后者会过滤掉 password 字段。

数据库字符集检测 — warning

数据库连接字符集必须为 utf8mb4（支持 emoji 等 4 字节字符）。

裸 htmlspecialchars 检测 — warning

禁止裸写 htmlspecialchars，必须用 esc_html() / esc_attr() / esc_js() 统一转义。

Bootstrap Tab 误用检测 — warning

仅扫描 .htm/.html 文件。外层导航（页面跳转）禁止用 Bootstrap Tab 系统（role="tablist" + data-bs-toggle="tab"），否则 Bootstrap 会把 <a href="./?xxx.htm"> 的 href 当作 CSS 选择器，触发 SyntaxError。应改为普通 <a> 链接跳转；内层导航（同一页面内的 tab 切换）才用 tab。

db_find_one 参数类型检测 — warning

db_find_one() 第 4 个参数 $col 必须传入数组（如 array('fid', 'uid')），禁止传入字符串以避免 implode() 参数类型错误。

install.php 非幂等建表检测 — warning

仅对 install.php 文件检测。install.php 所有建表语句必须用 IF NOT EXISTS 保证幂等。

Bootstrap 迁移规则

BS4 旧类名 — medium

BS4 旧 data 属性 — medium

BS3 旧类名 — medium

Bootstrap jQuery 插件调用 — warning

.button('loading') 在 Bootstrap 5 中已移除，应使用 htmx hx-disabled-elt 在请求期间禁用按钮，或用原生 JS 设置 btn.disabled = true。

前端迁移规则

jQuery 使用 — medium

Fontello 旧图标 — medium

非 Tabler Icons 图标库 — medium

采用 class 属性正则匹配模式，避免误匹配 fa- 出现在其他上下文（如变量名、注释）中。建议生成时会提取具体的 fa-xxx/bi-xxx/glyphicon glyphicon-xxx 类名，提示用户参考 Tabler Icons 查找对应图标。

代码规范规则

直接数据库操作 — info

仅检测 model/ 目录下的 PHP 文件中的原始 SQL 函数，避免业务路由的误报。

共 3 个 db_* 函数。此规则排除 install.php、uninstall.php、unstall.php、upgrade.php 文件（安装/升级脚本中直接操作数据库是合理的）。

保留注释抑制机制：

对于无法用 db_find* 替代的复杂 SQL（JOIN、系统表、复杂聚合等），在代码中添加包含 保留 db_sql_find 或 保留 db_exec 关键字的注释，扫描器会自动跳过后续 10 行的 direct_db 报告：

// 联表查询，db_find 不支持 JOIN，保留 db_sql_find
$sql = "SELECT a.*, b.name FROM a LEFT JOIN b ON a.id=b.id";
$rows = db_sql_find($sql);  // 此行不会被报告

支持的关键字格式（正则 /(保留|@suppress).*db_(?:sql_find|sql_find_one|exec)/）：

• // 保留 db_sql_find

• // 保留 db_sql_find_one

• // 保留 db_exec

• // @suppress db_sql_find

注释必须放在 db_* 调用上方 10 行以内。抑制区间为注释行 + 后续 10 行，覆盖多行 SQL 拼接。

迁移指南：

保留 db_sql_find / db_exec 的合理场景：

以下复杂 SQL 无法用 db_find* 系列替代，可在代码中添加注释说明保留原因：

• JOIN 查询：SELECT ... FROM a LEFT JOIN b ON ...（db_find 不支持 JOIN）

• 系统表查询：SELECT ... FROM INFORMATION_SCHEMA.*（如列存在性检查）

• 非 SELECT 语句：db_exec 执行 UPDATE ... SET x = GREATEST(x-1, 0)、INSERT IGNORE ... SELECT、含子查询的 DML

• 时间函数聚合：SELECT ... WHERE HOUR(FROM_UNIXTIME(...))（db_cond 不支持 SQL 函数）

db_find_group / db_find_one_group 使用示例：

// 替代：db_sql_find_one("SELECT uid, COUNT(*) as cnt FROM tbl GROUP BY uid HAVING cnt > 5")
$row = db_find_one_group(
    'tbl',                         // 表名（不含前缀）
    [],                            // WHERE 条件
    ['uid'],                       // GROUP BY 字段
    ['cnt' => ['>' => 5]],         // HAVING 条件（格式同 WHERE）
    [],                            // ORDER BY
    ['uid', 'COUNT(*) as cnt']     // SELECT 字段（聚合字段必须用别名）
);

// 替代：db_sql_find("SELECT fid, COUNT(*) as cnt FROM tbl GROUP BY fid ORDER BY cnt DESC LIMIT 10")
$rows = db_find_group(
    'tbl',
    [],
    ['fid'],
    [],
    ['cnt' => -1],                 // -1 降序，1 升序
    1, 10,                         // page, pagesize
    'fid',                         // 返回数组的 key 字段
    ['fid', 'COUNT(*) as cnt']
);

其他规则

conf.json 版本检查 — info

检查 conf.json 中 bbs_version 字段，若 < 4.5 则提示更新。

Hook 文件名检查 — info

检查 hook/ 目录下文件名是否符合 [a-z_][a-z0-9_]* 命名规范。

特殊处理逻辑

missing_csrf（跨行检测）

POST 表单的 CSRF 检测不能逐行匹配，因为 method="post" 和 CsrfService::input() 可能分布在文件不同位置。因此采用文件级检测：

1. 读取整个文件内容

2. 检查是否包含 method="post"

3. 若包含，再检查是否包含 CsrfService 或 csrf_token

4. 仅当 POST 表单存在且缺少 CSRF 令牌时才报告

direct_db（文件名排除）

安装/升级脚本中直接操作数据库是合理的，因此排除以下文件：

• install.php

• uninstall.php

• unstall.php（Xiuno 旧版拼写）

• upgrade.php

service_undefined_var（路径限制）

仅在 model/ 目录下的 PHP 文件中检测，避免误报业务路由中的同名变量。检测条件：当前行包含 SQL 关键字（SELECT/INSERT/UPDATE/DELETE/FROM/INTO）且引用了 $tableName 或 $tablePrefix。

文件级跨行检测

以下规则需要读取整个文件内容并使用正则跨行匹配，无法逐行扫描：

API 接口

扫描请求

GET /*****/?plugin-scanner-do.htm

返回 JSON 数组，每个元素代表一个插件的扫描结果：

[
  {
    "dir": "xn_tag",
    "name": "标签",
    "version": "1.0",
    "bbs_version": "4.0",
    "installed": true,
    "enable": true,
    "issues": [
      {
        "file": "plugin/xn_tag/hook/post_js.htm",
        "line": 15,
        "category": "jquery_usage",
        "match": "$.ajax(",
        "suggestion": "使用 htmx 或原生 fetch 替代 $.ajax",
        "severity": "medium",
        "context": "$.ajax({url: '...'})"
      }
    ],
    "total": 3,
    "fatal": 0,
    "warning": 1
  }
]

CSV 导出

GET /*****/?plugin-scanner-export.htm

下载 CSV 文件，包含所有插件的扫描结果。

指定插件导出

GET /*****/?plugin-scanner-export.htm&dir=xn_tag

仅导出指定插件的扫描结果。

扩展规则

如需添加新的扫描规则，按以下步骤操作：

行级检测规则

1. 在 lib/PluginScannerRules.php 的 getRules() 中添加新分类和匹配模式（仅适用于行级检测）

2. 在 getSeverityLevels() 中添加严重级别映射

3. 在 getCategoryNames() 中添加中文名称

4. 如果是 PHP-only 规则，在 getPhpOnlyCategories() 中添加（避免扫描 JS/CSS 内容）

5. 如果是 HTML-only 规则，在 getHtmlOnlyCategories() 中添加（避免扫描纯 PHP 文件）

6. 对于需要动态建议的分类，在 lib/PluginScannerSuggestion.php 的 build() 方法中添加 case 分支

7. 在 lang/zh-cn/bbs_*****.php、lang/zh-tw/bbs_*****.php、lang/en-us/bbs_*****.php 中添加 plugin_scanner_cat_* 语言项

文件级检测规则

对于跨行检测、文件头检测等无法逐行扫描的规则，在 lib/PluginScanner.php 的 scanPluginDir() 方法中添加相应代码，使用 buildIssue() 辅助方法构建 issue 数组。

严重级别约定

• fatal：PHP 8.0+ 下直接报错或崩溃（如废弃函数、注释陷阱、HEREDOC 错误、APP_PATH 误用）

• warning：安全风险或功能异常（如 CSRF 缺失、MD5 哈希、字符集错误、Tab 误用）

• medium：不兼容但不会崩溃，需要迁移（如 BS4/BS3 旧类名、jQuery 使用、图标库）

• info：建议优化，非必须（如 direct_db、conf.json 版本、Hook 文件名）