rd`）

date: 2026-09-30

category: 插件开发

source: WWW/docs/外链跳转弹窗插件开发计划_2026-09-30.md

外链跳转弹窗插件开发计划（external_link_guard）

编制：2026-09-30 ｜ 状态：📋 计划待拍板 —— 未动手，零代码改动

一句话：前台点击站外链接 → 弹「即将离开本站」确认框 → 用户确认后跳转；纯客户端事件委托拦截，零网络请求、零卡顿风险。

计划速览

一、结论摘要

1.1 做什么

1.2 与现有资产的边界（先划清，避免重叠）

⚠️ 与 notice_center 的共存细节：两者都在 layout_body_end 直出 DOM、都用 z-index:100010。

同 z-index 下后出现的 DOM 覆盖前者。对策：本插件根容器 z-index 取 100020（高于 notice_center 的 100010），

保证「公告弹窗 + 外链确认框」同时出现时确认框在最上层（详见 §3.5）。

1.3 不做什么

• ❌ 不改核心（不新增钩子、不动 Content.php）
• ❌ 不做服务端 302 中转页（那是 §11.30 的场景，用于点击计数，本插件不需要计数）
• ❌ 不做点击统计 / 埋点（避免 §11.31 的「每请求写库」性能坑）
• ❌ 不做「外链在编辑器预览区也拦截」（编辑器预览是后台页面，已整体排除）
• ❌ 不做 A/B、不做多语言文案以外的个性化

1.4 需你拍板 → §四（6 个点）

二、现状核查（实测，非推断）

2.1 ★ 钩子层：43 个钩子没有「内容重写」能力 → 服务端方案出局

$ grep -nE "^#{2,3} 9\." docs/插件开发规范.md
630:### 9.0 触发机制（实现细节）
667:### 9.1 核心钩子全表（43 个，按生命周期排序）
802:### 9.2 已废弃 / 陷阱钩子（勿使用）

逐组核对 §9.1 全表（docs/插件开发规范.md:667-798）：

结论（硬结论）：

核心没有提供任何「正文 HTML 输出后重写」的钩子（无 filter / 无 output buffer 回调）。

要做服务端重写，只有两条路：

① 改核心 Content.php（用户明确「形态：插件」→ 否决）；

② 输出缓冲（ob_start + 回调替换）—— ⚠️ 核心没有暴露任何 ob_start 钩子，

插件若自己在 init_after 里 ob_start()，会与核心的 PageCache（app/Helpers/PageCache.php）

和 header_register_callback（soundplayer 用过）互相打架，风险不可控 → 否决。

→ 唯一可行路线 = 客户端 JS 拦截（在浏览器里拦 click 事件）。

2.2 ★ 核心已给所有 <a> 加 target="_blank" + rel → 不能靠 target 判外链

app/Helpers/Content.php:123-126（DOM 净化后统一加）：

if ($tag === 'a') {
    $node->setAttribute('rel', 'noopener noreferrer nofollow');
    $node->setAttribute('target', '_blank');
}

app/Helpers/Content.php:577-584（纯文本自动链接）：

return '' . $safe . '';

关键推论（本方案的核心技术点）：

→ 唯一可靠判据 = 比对 host：new URL(a.href).host !== location.host。

附带发现（安全相关）：Content.php:116 的协议白名单是

if (!\preg_match('/^(https?:\/\/|mailto:|tel:|\/|#)/i', $value)) { $removeAttrs[] = $name; continue; }

其中 \/ 会放行协议相对 URL //evil.com（Content.php:149 自己都把它当外链：#^(?:https?:)?//#i）。

本插件的 host 比对天然会把它判为外链（URL('//evil.com').host = 'evil.com' ≠ 本站）→ 属于顺带加固。

2.3 弹窗 UI 基线：notice_center 全套可复用（实测）

plugins/notice_center/ 是同一天落地的同类弹窗，其结构可直接复用：

plugins/notice_center/assets/style.css 头部注释里那三条硬约束同样适用于本插件：

/* ⚠️ 只用核心**已定义**的 `--mn-*` 变量
 * ⚠️ 隐藏工具类一律 `display: none !important`：插件 CSS 在 `main.php:40` 注入，
 *    **早于**核心 `editor.css` → 同权重核心后胜；不给 `!important` 会被静默压掉。
 * ⚠️ z-index 取 100010 —— 核心浮层天花板实测为 100005（`.image-lightbox` = 99999）。
 */

2.4 核心没有弹窗组件（实测）

$ grep -nE "^\.mn-(btn|panel|modal|dialog|overlay)\b" assets/css/modern.css
522:.mn-panel            ← 有
531:.mn-panel-title      ← 有
1067:.mn-btn             ← 有
1089:.mn-btn-primary     ← 有
1100:.mn-btn-sm          ← 有
2116:.mn-btn-block       ← 有

$ grep -cE "mn-modal|mn-dialog" assets/css/modern.css
0                       ← 弹窗类**不存在**

$ ls -1 assets/js/
auth.js  editor.js  lightbox.js  marked.min.js  pow.js  thread.js  turndown*.js
                        ↑ 核心**没有**通用 modal / confirm 工具

→ 弹窗容器必须自建；但按钮 / 面板类可复用（这正是「与现有 UI 一致」的落点，见 §3.5）。

2.5 z-index 天花板 = 100005（沿用 notice_center 实测）

docs/全站公告弹窗插件开发方案_2026-09-30.md:114-118 实测：

assets/css/*.css 的 z-index 分布：9999 ×1、99999 ×2、100000 ×4、100005 ×1

→ 弹窗取 100010（必须高于全部核心浮层，否则被灯箱/顶栏盖住）。

本插件取 100020（比 notice_center 高一级，见 §1.2）。

2.6 正文容器 = .post-text-content（决定「拦截范围」选项）

→ 若决策 1 选「仅正文内拦截」，选择器就是 .post-text-content（核心类，稳定，非插件自造）。

2.7 可复用资产（省事清单）

2.8 硬约束（实测，直接决定设计）

1. 零内联（§7.3）：禁内联 <style> / <script> 块、style="" 属性、on 事件属性 → 全部收敛到 assets/，传参走 data-。

> ⚠️ docs/插件审计报告.md:130 已记录过一次同类事故：「内联事件属性违反零内联红线，且受 CSP script-src 策略限制时确认弹窗会失效」—— 本插件是整个功能就是弹窗，踩这条 = 功能直接不可用。

1. 渲染钩子里 $this 不可用（§11.24）：layout_body_end / layout_head_end 运行在闭包作用域 → 一律 htmlspecialchars($s, ENT_QUOTES, 'UTF-8') + I18n::get()。
2. layout_body_end 无参数（§9.1 #43）→ 判「是否后台页」只能靠请求路径 /admin 前缀（notice_center 的 Plugin::isBackend('') 已实现此逻辑，可直接抄）。
3. layout_body_end 全站触发（含后台） → 必须显式排除后台，否则后台也会注入弹窗。
4. 改 layout_head_end / layout_body_end 后必须 PageCache::invalidate()（§11.5 第 31 条）—— 后台保存配置后触发。
5. CSP（app/Core/Controller.php:80）：img-src 'self' data: https: → 本插件弹窗不放图，无影响。
6. Service Worker（§11.5 第 35 条）：同源 GET 非导航一律 Cache-First → 本插件纯客户端、零请求，不受影响。
7. 后台视图容器三件套（§11.3 第 22 条）：.admin-container + admin/_sidebar + <main class="admin-content">，弹层必须在 <main> 内。
8. 开关字段必须用表单哨兵（§11.32 / §11.18）：不能用 (int)($_POST[$k] ?? 0)。
9. 目录名含下划线 → 必须 class_alias（§4.1 / §11.12）。

三、技术设计

3.1 ★ 方案选型

选 ③ 的决定性理由：

- 唯一不改核心就能落地**的路线（① ② 都卡在「没有内容重写钩子」）；

- 零卡顿风险 —— 这是上一次 soundplayer 悬浮窗被砍的原因。

本插件：服务端不查库（空壳 DOM）、客户端只挂一个 document 监听器、无轮询、无音频解码、无定时器。

开销 ≈ 一次 addEventListener，可忽略。

③ 的固有代价（如实列出）：

3.2 目录结构

plugins/external_link_guard/
├── plugin.json                      # 清单（activated:false 起步，待你确认后启用）
├── Plugin.php                       # 主类：设置读写 / 渲染 / 判定
├── AdminController.php              # 后台配置页（继承 Admin\BaseController）
├── hook/
│   ├── layout_head_end.php          # </head> 前：注入 CSS/JS（带 shouldInject 门控）
│   └── layout_body_end.php          # </body> 前：直出弹窗空壳 DOM
├── views/
│   └── admin.php                    # 后台配置页（容器三件套）
├── assets/
│   ├── style.css                    # 弹窗样式（复用 notice_center 范式）
│   └── script.js                    # 事件委托拦截 + 弹窗控制
├── lang/
│   ├── zh.php / zh_tw.php / en.php  # 三语（键集合零差异 + 键序一致）
└── 说明.md                          # 插件文档（仓库约定，每个插件根目录一份）

命名空间 ↔ 目录名（⚠️ 最易踩的坑）：

// Plugin.php 末尾（照抄 notice_center/Plugin.php:892-894）
if (!\class_exists('Plugin\\external_link_guard\\Plugin', false)) {
    \class_alias(Plugin::class, 'Plugin\\external_link_guard\\Plugin', false);
}

⚠️ class_alias 之外还有一层：§11.34（2026-09-30 新增）—— 命名空间首段必须逐字节等于目录名。

上面「目录名 external_link_guard + 命名空间 ExternalLinkGuard」的组合满足该条（靠 camelToSnake 映射）。

反面教材：Plugin\AdSlot → camelToSnake 得 ad_slot ≠ adslot → Windows 假通过、Linux 500。

3.3 ★ 外链判定规则

核心函数（客户端）：

/* 判定一个  是否「站外链接」。返回 true = 需要弹窗确认。 */
function isExternalLink(a) {
    var raw = a.getAttribute('href') || '';
    if (raw === '' || raw.charAt(0) === '#') {          // ① 锚点 / 空
        return false;
    }
    if (/^(javascript|data|vbscript):/i.test(raw)) {    // ② 伪协议（核心已拦，纵深防御）
        return false;
    }

    var url;
    try {
        url = new URL(a.href, location.href);           // a.href 已是解析后的绝对 URL
    } catch (e) {
        return false;                                   // 解析失败 → 放行（不阻断用户）
    }

    if (url.protocol === 'mailto:' || url.protocol === 'tel:') {
        return false;                                   // ③ 邮件 / 电话 → 见决策 4
    }
    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
        return false;                                   // ④ 只拦 http(s)
    }

    if (url.host === location.host) {                   // ⑤ 同域豁免（host 含端口，比 hostname 精确）
        return false;
    }
    if (isWhitelisted(url.hostname)) {                  // ⑥ 站长白名单
        return false;
    }
    return true;
}

豁免清单（逐条说明）：

白名单匹配规则（建议）：

/* 支持精确域名与一级子域通配：example.com 匹配 example.com / www.example.com */
function isWhitelisted(hostname) {
    hostname = hostname.toLowerCase();
    for (var i = 0; i < WHITELIST.length; i++) {
        var d = WHITELIST[i];
        if (hostname === d || hostname.slice(-(d.length + 1)) === '.' + d) {
            return true;
        }
    }
    return false;
}

⚠️ 不要用 endsWith(d) 裸匹配 —— evil-example.com.endsWith(example.com) 会误放行。

必须带 . 前缀（'.' + d）才能保证是子域而非「后缀相同的另一个域」。

子域问题（决策 1 的延伸）：本站若部署在 www.example.com，而站内有指向 bbs.example.com 的链接，

按 ⑤ 会被判为外链。对策：白名单里加 example.com 即同时覆盖两个（靠上面的子域通配）。

3.4 DOM 注入链路

沿用 notice_center 的双钩子范式（plugins/notice_center/hook/*.php）：

main.php:40   layout_head_end ──┐
                                ├─→  Plugin::shouldInject()   ← 总开关 + 非后台 判定
                                └─→    +  

为什么弹窗 DOM 是「空壳」（本插件比 notice_center 更简单）：

**注入参数（data-*，零内联要求）**：

     data-elg-mode="all">                             
    

    

        
即将离开本站
        
你要访问的是站外地址：
        
          
        

            留在本站
            继续访问   
        
    

3.5 弹窗 UI（与现有 UI 一致）

「一致」的落点 —— 逐条对应：

⚠️ 不自己造按钮样式：核心 .mn-btn / .mn-btn-primary 是全局类（modern.css 无作用域前缀，任意页面可用）

→ 直接用即可，天然与全站按钮一致，且核心将来改按钮样式会自动跟随。

z-index 口径：.elg-root { z-index: 100020 }（高于核心天花板 100005 与 notice_center 的 100010）。

隐藏类写法（照 notice_center 的教训）：

.elg-root[hidden] { display: none !important; }

⚠️ !important 不能省：插件 CSS 在 main.php:40 注入，早于核心 editor.css（:65）→ 同权重时核心后胜，不给 !important 会被静默压掉（notice_center/assets/style.css:6-7 原话）。

3.6 交互细节

「只拦一次」的边界：用户点「继续访问」→ 跳转 → 用户点浏览器「后退」回到本站 →

弹窗状态必须已复位（root.hidden = true）。由于跳转是新标签（target="_blank"），

本站页面从未离开，弹窗保持打开状态 → ⚠️ 需要在确认跳转时立即关闭弹窗（见 §3.7）。

3.7 ★ 「确认后跳转」的实现（关键，含弹窗拦截器风险）

三种做法对比：

采用 ③ 的完整流程：

用户点外链 
        │
        ├─ 捕获阶段 handler：isExternalLink() → true
        │   ├─ e.preventDefault()              ← 阻止本次默认跳转
        │   ├─ 记录 elgPendingUrl = a.href
        │   ├─ root.hidden = false             ← 显示弹窗
        │   └─ document.getElementById('elgGo').href = a.href   ← 填进「继续访问」
        │
        └─ 用户点「继续访问」（真实手势 → 新标签打开，不被拦截）
            ├─ 立即 root.hidden = true          ← ⚠️ 关弹窗（本站页面不会离开）
            └─ 浏览器新标签打开目标

⚠️ 为什么必须「点确认时立即关弹窗」：因为跳转发生在新标签，本站页面始终在原标签。

若不关，用户回到原标签会看到弹窗还开着，且 body.elg-lock 还锁着滚动 → 页面卡死观感。

「留在本站」按钮：<button data-elg-close="1"> → 只关弹窗，不跳转（elgPendingUrl 丢弃）。

为什么不用 window.open：见上表 ①。这是本方案最容易踩的坑 —— 本地开发（localhost）往往不拦弹窗，

生产环境（真实用户浏览器设置）会拦，属「本机测不出、线上才暴露」类故障。

3.8 后台配置页

路由（hook/admin_route_register.php）：

if (!isset($router)) {
    return;
}
// ⚠️ 不写 /admin 前缀（核心已 group('/admin')，写了 404 —— §11.22）
$router->get('/external-link-guard',  ['\Plugin\ExternalLinkGuard\AdminController', 'index']);
$router->post('/external-link-guard', ['\Plugin\ExternalLinkGuard\AdminController', 'save']);

控制器：继承 app\Controllers\Admin\BaseController（门禁在构造函数，§11.3）+ PRG + flash 读后即焚。

视图：容器三件套（§11.3 第 22 条）

    <?php $this->include('admin/_sidebar'); ?>
    
        
… 表单 …
    

配置项（建议）：

保存逻辑（⚠️ 开关字段的坑）：

public static function saveSettings(array $post): void
{
    // ⚠️ 不能用 (int)($post['enabled'] ?? 0) —— 字段缺失会被静默写成最小值
    //    （302 + 提示成功，但 DB 与 settings_cache.php 都不变、error.log 无记录 —— §11.32）
    //    必须用「表单哨兵」判断表单是否提交过。
    if (!\array_key_exists(self::FORM_SENTINEL, $post)) {
        return;
    }
    Settings::update(self::K_ENABLED, !empty($post['enabled']) ? '1' : '0', self::PLUGIN);
    Settings::update(self::K_WHITELIST, self::normWhitelist((string)($post['whitelist'] ?? '')), self::PLUGIN);
    Settings::update(self::K_MODE, self::normMode((string)($post['mode'] ?? 'all')), self::PLUGIN);
}

白名单归一化（服务端也做一遍，纵深防御）：

/* 只留合法域名：小写、去掉协议/路径/端口、去重 */
private static function normWhitelist(string $raw): string
{
    $out = [];
    foreach (\preg_split('/[\s,，;；]+/u', $raw) as $d) {
        $d = \strtolower(\trim($d));
        $d = \preg_replace('#^[a-z]+://#', '', $d);        // 去协议
        $d = \strtok($d, '/');                            // 去路径
        $d = \preg_replace('/:\d+$/', '', (string)$d);    // 去端口
        if ($d !== '' && \preg_match('/^[a-z0-9.-]+\.[a-z]{2,}$/', $d)) {
            $out[$d] = true;
        }
    }
    return \implode(',', \array_keys($out));
}

保存后必须清缓存（§11.5 第 31 条）：PageCache::invalidate()（否则游客拿到旧配置的整页缓存）。

3.9 i18n

前缀 plugin.external_link_guard.（§11.3 第 19 条）。三语键集合零差异 + 键序一致（用单一数据源生成）。

预估键表（前台 8 + 后台 12 ≈ 20 键）：

⚠️ 前台文案是弹窗骨架的一部分（服务端直出）→ 改文案后必须清页面缓存。

3.10 明确不做的（极简取向）

• ❌ 不建数据表 —— 本插件零持久化数据（配置走 Settings，前端状态无）→ 不需要 ddlStatements() / ensureSchemaOnce() / uninstall() 删表。
• ❌ 不做「不再提醒此站点」的持久化（可选，见决策 3）—— 若做，用 localStorage（游客安全）或 Settings（不需要）。
• ❌ 不做点击统计（§11.31 性能坑）。
• ❌ 不做「复制链接」按钮（可选增强，先不做；用户审美 = 没有实际用途的控件不出现）。
• ❌ 不做「外链在编辑器预览区拦截」（后台已排除）。
• ❌ 不注册前台路由（无中转页需求 → 不需要 route_register 钩子）。
• ❌ 不注册 nav_plugin_links（无前台入口需求）。

四、需你拍板的 6 个点

决策 1：拦截范围 —— 全站所有外链，还是仅正文内？

我的建议：C。因为「防流失」的真实场景（用户点正文里的外链走了）主要在正文，

但友链/公告的拦截需求因站长而异 → 给开关比替你选更合适。

决策 2：插件目录名

检查过：plugins/ 下无 link / external / jump / redirect 相关目录 → 无占用冲突。

决策 3：是否提供「不再提醒此站点」？

决策 4：mailto: / tel: / 修饰键 / 中键 要不要拦？

决策 5：带 download 属性的链接要不要拦？

决策 6：弹窗里要不要显示完整 URL（而非只显示域名）？

五、实施阶段（P0 ~ P4，每阶段末停下确认）

⚠️ 每阶段末停下等你确认（沿用你的协作习惯）。

⚠️ plugin.json 的 activated 默认 false —— 由你决定何时启用。

六、风险与坑（逐条对应规范）

七、验证清单

7.1 静态检查（每次改动后）

7.2 HTTP 端到端冒烟（必须，skill 红线 3）

⚠️ 「只跑 php -l + i18n + 零内联证明不了拦截逻辑生效」→ 必须补真实 HTTP。

7.3 浏览器交互（你自测 —— 界面与观感）

八、附：证据索引（本计划全部结论的出处）

下一步：请就 §四 的 6 个决策点 给出选择（或直接说「按你的建议来」），我再进入 P0。

本文档为纯计划，未产生任何代码改动。