浏览器 XSLT 退场后:把 XML 目录迁到构建期 HTML

以受控 XML 文档目录为例,使用 Python 标准库实现构建期 HTML 生成,说明输入协议、文本转义、失败保留旧页面、测试边界与发布回滚。

浏览器里直接打开 XML,再由一张 XSL 样式表变成文档目录,这种交付方式把一个不显眼的依赖交给了访问者的浏览器。页面没有大型前端框架,也没有复杂接口,却可能因为原生转换能力退出而失去可读视图。迁移时最容易走错的方向,是把“继续显示 XML”当成“继续执行 XSLT”,或者只是删掉样式表声明,以为页面仍然完整。

截至 2026 年 11 月 18 日,Chrome 的移除说明仍将 Chrome 158、2026 年 11 月 17 日列为稳定版原生 XSLT 停用节点,临时试用和企业策略参与者有例外。这是一项官方计划与兼容性边界,不是本文对所有设备完成升级的实测。移除对象包括 XSLTProcessor 和 XSLT 样式处理指令;XML 本身及 XML 配合 CSS 的展示不是同一回事。不要由这条消息推断某个站点已经受损,先确认它到底在哪里运行转换。

本文选择一个具体且容易验收的改造:把受控文档目录的 XML,在构建阶段生成普通 HTML,浏览器只负责展示。代码不是 XSLT 引擎,不承诺执行任意样式表;它针对一个小而明确的数据协议重新实现展示逻辑。适用前提是内容由可信编辑流程管理、发布频率低于访问频率、不需要按访问者实时计算。如果实际系统是一套包含复杂模板匹配、扩展函数和多文件导入的 XSLT 应用,先做语义盘点,不应拿这个例子直接替换。

先定位转换发生在哪一层

第一轮检查应覆盖源代码、构建结果和真实入口,而不是只搜前端源码。可以在项目根目录运行下列命令;它们是排查建议,本文没有对读者的私有项目执行搜索。

rg -n -i 'XSLTProcessor|xml-stylesheet|text/xsl|application/xslt' src public dist

没有 rg 的环境可使用编辑器全局搜索。src、public、dist 要替换为自己的目录,避免把不存在的路径当成“零命中”。命中后记录三个事实:谁提供 XML、谁提供 XSL、谁实际完成转换。一个后端调用转换库、返回 text/html 的接口,与浏览器加载 XML 后执行样式表是两条不同链路;前者不能仅因浏览器变更就被列为故障。

源码零命中也不能直接收工。历史静态资产、第三方导出包、用户收藏的旧 XML 地址,以及服务端按参数生成的处理指令,都可能不在当前前端目录里。选取真实访问入口检查响应类型和正文,再在测试环境验证。浏览器可用性检查只是诊断证据,不应该成为生产逻辑里唯一的回退条件;同一条 XML 地址如果没有设计 HTML 替代入口,能力检测失败之后仍然没有可用内容。

我的取舍是优先把“给人看”的页面与“给机器取数”的接口分开。比如保留 /catalog.xml 的数据职责,新增 /catalog/ 的 HTML 页面。不要为了修复视觉展示,突然把已有 XML 地址改成 HTML,破坏订阅者、下载工具或后端集成。是否重定向旧地址,应由调用方盘点决定,而不是由迁移脚本顺手处理。

为目录定义一个可拒绝的输入协议

下面的输入只包含根元素、条目和两段纯文本。条目顺序就是页面顺序,空目录合法;每条记录的 slug 必须唯一,并且只能由小写字母、数字及中间的连字符组成。标题和摘要不能包含子元素。这样的限制不是 XML 的限制,而是我们主动收紧应用协议,使迁移后的行为能够解释和测试。

<catalog>
  <item slug="quick-start">
    <title>快速开始 &amp; 环境检查</title>
    <summary>先确认版本,再运行最小示例。</summary>
  </item>
</catalog>

输入文件采用 UTF-8,不带 XML 声明、注释、DTD、CDATA 或处理指令。旧文件中的 xml-stylesheet 不会由代码悄悄忽略,而应在审查迁移后主动移除;否则构建失败,提醒维护者仍有旧契约未处理。需要注释、命名空间或混合内容的系统,应显式扩展协议并增加测试,而不是删除所有校验让它“先跑起来”。

本例只处理可信仓库内的文件,不提供公众上传接口。即使做了字节大小和声明检查,也不能把它包装成通用的恶意 XML 沙箱。Python 的 ElementTree 文档要求不可信输入场景另看 XML 安全说明;若未来接收外部文件,应另外选择和审计解析器、防护策略、超时及资源隔离。把离线工具搬进 HTTP 请求处理函数,是安全边界的改变,不是一次无成本复用。

关键实现:校验、转义、一次性替换输出

保存为 build.py。仅使用 Python 标准库,本文实际执行环境是 Python 3.12.14。代码先读至多一 MiB 加一个字节以识别超限,完整验证并构造输出后,才在目标目录创建临时文件,最后替换目标文件。目标目录需事先存在;路径是构建人员给定的本地路径,不接受来自网页参数的任意路径。

from pathlib import Path
from html import escape
import os
import re
import sys
import tempfile
import xml.etree.ElementTree as ET

MAX_BYTES = 1024 * 1024
MAX_ROWS = 1000
SLUG = re.compile(r'[a-z0-9]+(?:-[a-z0-9]+)*')

def render(raw):
    if len(raw) > MAX_BYTES:
        raise ValueError('input too large')
    text = raw.decode('utf-8', errors='strict')
    if '<!' in text or '<?' in text:
        raise ValueError('declarations, comments and PI are not allowed')
    root = ET.fromstring(text)
    if root.tag != 'catalog' or root.attrib:
        raise ValueError('invalid root')
    if (root.text or '').strip() or len(root) > MAX_ROWS:
        raise ValueError('invalid catalog')
    rows, seen = [], set()
    for item in root:
        if item.tag != 'item' or set(item.attrib) != {'slug'}:
            raise ValueError('invalid item')
        slug = item.attrib['slug']
        if len(slug) > 80 or not SLUG.fullmatch(slug) or slug in seen:
            raise ValueError('invalid or duplicate slug')
        seen.add(slug)
        if (item.text or '').strip() or (item.tail or '').strip():
            raise ValueError('unexpected mixed text')
        if [node.tag for node in item] != ['title', 'summary']:
            raise ValueError('expected title then summary')
        values = []
        for node, limit in zip(item, (160, 1000)):
            value = (node.text or '').strip()
            if node.attrib or len(node) or (node.tail or '').strip():
                raise ValueError('plain text fields required')
            if not value or len(value) > limit:
                raise ValueError('invalid field length')
            values.append(escape(value, quote=True))
        title, summary = values
        rows.append(f'<li><a href="/docs/{slug}/">{title}</a><p>{summary}</p></li>')
    return ('<!doctype html><html lang="zh-CN"><meta charset="utf-8">'
            '<meta name="viewport" content="width=device-width,initial-scale=1">'
            '<title>文档目录</title><body><main><h1>文档目录</h1><ul>'
            + ''.join(rows) + '</ul></main></body></html>')

def build(source, target):
    source, target = Path(source), Path(target)
    if source.resolve() == target.resolve():
        raise ValueError('input and output must differ')
    with source.open('rb') as f:
        output = render(f.read(MAX_BYTES + 1))
    temp = None
    try:
        with tempfile.NamedTemporaryFile(mode='w', encoding='utf-8',
                dir=target.parent, delete=False) as f:
            temp = Path(f.name)
            f.write(output)
        temp.chmod(0o644)
        os.replace(temp, target)
        temp = None
    finally:
        if temp is not None:
            temp.unlink(missing_ok=True)

if __name__ == '__main__':
    if len(sys.argv) != 3:
        raise SystemExit('usage: python3 build.py source.xml target.html')
    build(sys.argv[1], sys.argv[2])

这里有四个值得保留的设计决定。

首先,解析成功并不代表符合业务协议。XML 解析器解决结构是否成立,我们继续验证根元素、属性集合、子节点顺序和字段长度。额外字段直接拒绝,而不是静默丢弃。这样可以在上游增加字段时暴露版本分歧,不让发布过程貌似成功却丢失重要信息。字段中的前后空白被明确裁剪,如果空白在业务上有语义,就应取消这一步并调整测试。

其次,显示文本与链接路径使用不同的保护方式。标题和摘要先由 XML 解析还原文本,再用 html.escape 写入 HTML 文本位置。官方 html 文档说明了字符及引号转义行为。不要把 XML 原文直接拼进 HTML,否则同一段字符可能在两个语法层里被重复解释。slug 则采用窄字符协议,并放在固定站内路径中,不接收任意 URL。因此本例不需要猜测 javascript:、协议相对地址或外部跳转是否应该允许。HTML 转义不能替代 URL 策略,二者解决不同问题。

再次,输出不是边解析边覆盖线上文件。坏 XML、重复标识或过长字段都会在替换前失败,现有页面保持不变。临时文件与目标文件在同一目录,避免跨文件系统移动;os.replace 文档描述了成功替换的原子性及跨文件系统限制。不过,这不是断电耐久性承诺,代码没有执行文件和目录的同步落盘,也没有分布式发布事务。它只缩小单机生成阶段的半成品窗口。对象存储或多节点部署应使用自己的版本化发布机制。

最后,脚本禁止输入输出解析为同一路径,避免普通误操作覆盖源 XML。它仍然假设工作目录和发布进程受信任,不抵御其他本机进程恶意替换符号链接的竞争。多任务同时写同一个输出也没有协调锁,结果可能是最后写入者生效。构建系统应保证同一发布目标只有一个提交者,或者把产物写到每次构建独立的版本目录,再由一个发布步骤切换版本。

运行方式与明确的失败结果

创建 catalog.xml 并填入前面的例子,然后执行:

mkdir -p dist
python3 build.py catalog.xml dist/catalog.html
python3 -m http.server 8000 --directory dist

最后一条只用于本机演示,不是生产 Web 服务方案。打开 http://localhost:8000/catalog.html 应看到目录标题与一条链接。/docs/quick-start/ 是样例约定的业务地址,演示目录没有提供对应文档,所以点击它出现不存在页面是预期限制;接入实际站点时必须验证每条链接能到真实内容。不要把生成器测试通过等同于所有目标文档可用。

正常构建不输出额外文本,并以零退出码结束。把 slug 改为 ../secret、重复一条记录、添加 <b> 子元素或加入 XML 声明,构建应抛出异常并以非零码结束。部署流水线必须在该步骤失败时停止,不能用 || true 忽略它,再继续上传旧产物却标记为新发布。生产中可包装更友好的错误提示,但日志只需标明文件与规则,不必完整打印可能含内部内容的输入。

空目录虽然合法,也值得单独设置业务告警。一个知识库突然从几百条变成零条,可能是上游导出失败,而不是正常的空状态。语法层接受空目录,发布层可以依据上一版数量或本次变更意图拦截异常下降。这种门槛属于业务决策,不适合硬编码成所有系统通用的“至少十条”。

实际测试覆盖到哪里

本文在 Python 3.12.14 中运行了十三项 unittest 测试,全部通过:普通目录渲染、危险文本转义、重复 slug、非法路径字符、声明及处理指令拒绝、输入大小上限、错误编码、嵌套标签、额外字段、空目录、坏输入保留旧输出、正常文件写入和同路径拒绝。其中非法 slug 和声明测试分别包含多个子案例。这些是生成器与本地文件行为验证,不是对浏览器原生 XSLT 停用的验证。

下面是一份可直接保存为 test_build.py 的最小回归检查,用于展示关键验收方式。它不是前述十三项测试的完整清单,读者可在此基础上扩展自己的数据边界。

import tempfile
import unittest
from pathlib import Path
from build import build, render

class Regression(unittest.TestCase):
    def test_text_is_not_markup(self):
        raw = b'''<catalog><item slug="a"><title>&lt;script&gt;</title>
        <summary>text</summary></item></catalog>'''
        result = render(raw)
        self.assertIn('&lt;script&gt;', result)
        self.assertNotIn('<script>', result)

    def test_failure_preserves_old_page(self):
        with tempfile.TemporaryDirectory() as directory:
            root = Path(directory)
            source, target = root/'in.xml', root/'out.html'
            source.write_bytes(b'<broken')
            target.write_text('old', encoding='utf-8')
            with self.assertRaises(Exception):
                build(source, target)
            self.assertEqual(target.read_text(encoding='utf-8'), 'old')

if __name__ == '__main__':
    unittest.main()

运行 python3 -m unittest -v。如果把最小回归文件与完整测试放在同一目录,测试数量会相加,不要以固定数字作为成功条件;应看失败与错误数量,并核对实际发现了哪些测试。代码修改后重新执行,不能沿用旧提交的通过结果。

本文未进行真实浏览器渲染、键盘与屏幕阅读器测试,也没有验证 CDN、代理、生产域名及浏览器企业策略。上线前至少应检查 HTML 返回类型与 UTF-8 编码、标题可读性、长摘要换行、移动端布局、链接目标、键盘导航以及禁用 JavaScript 时的内容。由于输出没有脚本,本方案在设计上不依赖 JavaScript 转换,但真实页面外围主题仍可能加入脚本,不能把局部模板的性质扩展为整站保证。

发布与回滚不要重新依赖旧能力

推荐让 XML、生成脚本、测试和 HTML 产物对应同一个版本。构建日志记录输入摘要、脚本版本与生成条目数,发布时只切换已经完整验收的产物;不要先发布新 XML,几分钟后才补新 HTML,制造读者看到不同版本的窗口。如果两者必须分开缓存,则明确各自更新时间与最大允许延迟,出现不一致时能追溯到具体发布批次。

HTTP 缓存也应有自己的契约。静态资源可以使用内容指纹,目录页面可采用短缓存或按发布版本失效;但具体缓存头要与站点现有策略一致。本文没有给出一个对所有 CDN 都正确的强缓存天数,因为目录内容的更新频率、回滚速度与数据敏感性并不相同。含用户私有数据的页面更不能直接放入共享公开缓存。

回滚目标应该是上一版已经生成好的 HTML,而不是“重新打开浏览器原生 XSLT”。后者在不同设备上可能已经不可用。保留旧 XML 可以帮助排查数据变化,但不能充当展示层恢复方案。切换失败时,优先恢复完整旧产物,再分析新输入或模板问题,而不是在线放宽校验绕过阻塞。

如果必须保留完整 XSLT 语义,可以评估服务端转换引擎或客户端兼容实现。但选型标准应包含样式表兼容性、资源访问边界、依赖维护、执行开销和测试语料,不能仅比较一个示例是否渲染成功。对简单目录,窄协议加构建期生成通常更容易维护;对既有复杂转换系统,重写可能比保留引擎更危险。决定迁移方式的关键不是工具名字,而是你能否说明输入如何变为输出,并在失败时保住一个仍能访问的版本。

相关文章

评论

登录后即可参与讨论

暂无评论。