Skip to content

v0.7.2 迁移说明

历史文档

本页只描述 0.7.1 → 0.7.2，不能作为 0.8 API 或配置依据。升级到当前版本请阅读 v0.8 迁移指南。

v0.7.2 修复远程 Playwright 无法读取 Bot 容器内 file:// 模板的问题，并把资源准备、缓存和后端执行统一到同一套生命周期模型。v0.7.1 已发布公共 API 保持兼容；本页列出默认行为变化和需要主动迁移的含糊配置。

pre-1.0 兼容策略

项目当前仍处于 0.x。v0.7.2 以“保护已发布 API，同时修正不可靠默认值和未发布接口”为兼容原则，不宣称遵循 SemVer 对 patch 版本的兼容承诺。升级前应按本页完成回归。

远程 Markdown 不再访问包内 file://

v0.7.1 的 md_to_pic / render_markdown 可能让远程 Chromium 打开 Bot 容器中的模板路径：

file:///app/.venv/lib/python3.x/site-packages/
  nonebot_plugin_htmlrender/templates/markdown/markdown.html

当 Playwright 运行在另一个容器时，这会在 page.goto() 阶段得到 ERR_FILE_NOT_FOUND。v0.7.2 的内置模板在 Bot 进程中渲染为 HTML，随后通过 page.set_content() 注入；页面本身不依赖远端 filesystem。

以下配置可以继续使用，不需要手工增加 HTTP base_url：

RENDER_BACKEND=playwright
RENDER_PLAYWRIGHT={"connect_ws":{"endpoint":"ws://playwright:53333/playwright"}}

远程资源默认改为内存桥

远程 session 的有效默认组合变为：

resource_resolve_mode = auto
remote_local_resource_policy = memory

本地图片、字体、CSS 与模板资源读取为 PreparedAsset，按 SHA-256 去重，并通过当前Page 的 route 直接返回 bytes、正确媒体类型、cache header 与Access-Control-Allow-Origin: *。这些资源 payload 不写持久化目录或其他磁盘位置，Page 关闭后释放；Playwright 浏览器文件与 runtime snapshot 仍可使用插件数据目录。

如果你依赖旧行为，请显式声明意图：

  • 共享卷且 Bot/Chromium 使用完全相同的路径：remote_local_resource_policy=passthrough；
  • 需要浏览器外部也能访问的 HTTP URL：安装 [filehost] 并设置 remote_local_resource_policy=filehost；
  • 希望任何本地引用都失败：remote_local_resource_policy=error。

filehost 的 TTL 现在明确为 URL mapping TTL。它不承诺逐文件物理删除；物理文件由 nonebot-plugin-filehost 的进程级临时目录生命周期管理。

分离 base_url 与 document_url

v0.7.2 固定以下语义：

  • PreparedHtml.base_url：解析 HTML/CSS 的相对资源，不触发导航；
  • PageConfig.document_url：显式要求 page.goto() 的页面 URL。

v0.8 已删除 PageConfig.base_url 兼容别名；实际导航目标必须使用 document_url：

# Before: one field carried two meanings
pages = {"base_url": "https://render.example/card"}

# After: navigation is explicit
pages = {"document_url": "https://render.example/card"}

资源 origin 由 preparation source 或 prepare_html(..., base_url="https://render.example/assets/") 放入 PreparedHtml.base_url，不再混入 Page 配置。

普通 text、Markdown、模板与 rasterize_html 不需要 document_url，默认在 about:blank 上直接 set_content()。远程 file:// 文档导航不再作为默认资源传输方案；只有显式 passthrough 且浏览器确实挂载同一路径时才可使用。

内置模板属于 wheel

text 与 Markdown 模板只随 distribution 分发：

  • 使用 importlib.resources 与 Jinja PackageLoader 读取；
  • 文件登记在 wheel RECORD；
  • 卸载 Python package 时随 distribution 自动删除。

它们不会复制到插件数据目录。项目不提供 uninstall hook、模板复制、持久化目录清理或用户覆盖目录。render_cache_path 与 render_config_path 当前为保留配置，没有模板消费者；进程内 cache 和 PreparedAsset 也不在这些目录落盘。

用户模板仍由 render_template(template_path=...) 从显式 filesystem 目录读取。

Prepared model 变更

v0.7.2 的内部/新 API 契约为：

  • PreparedHtml.html 保留原始浏览器文档；
  • PreparedStylesheet(css, base_url, embedded, media) 结构化表达样式；
  • PreparedAsset.source 是文档资源标识，bytes 由两个后端共用；
  • PreparedAssetIndex 负责 exact 与相对基址规范化匹配。

当前开发分支曾短暂公开但从未发布的 PreparedHtml.markup，以及 TEMPLATES_PATH、TEXT_TEMPLATES_PATH、MARKDOWN_TEMPLATES_PATH、TEXT_TEMPLATE_FILE、MARKDOWN_TEMPLATE_FILE 五个 Path 常量已撤回。它们不属于 v0.7.1 兼容范围，也不应成为用户代码依赖。

Takumi 后端

安装方式：

uv add "nonebot-plugin-htmlrender[takumi]"

该 extra 精确锁定 takumi-py==0.2.0。Takumi 与 Playwright 共用 preparation、资源 bytes、Jinja 和 filesystem cache，但保持能力边界：

  • 只支持静态 HTML/CSS，不执行 JavaScript 或网络页面；
  • 只向 native 传实际引用的图片；
  • Python/Rust 边界前严格验证 UTF-8；
  • compiled cache 同时受 entry 与 32 MiB 默认 weight 上限约束；
  • filesystem 字体默认 revalidate，内容变化后需重建 runtime；
  • 无法表达的 <style media> 等条件 stylesheet 明确抛出 TakumiUnsupportedError，不会静默提升为全局 CSS。

需要 JS、网页导航、元素截图或完整浏览器布局时继续使用 Playwright。

可选遥测插件改为按配置选择性引导

v0.7.1 在导入阶段无条件 require 两个可选插件（只要装了就加载），且 Prometheus 默认启用。v0.7.2 改为**按 htmlrender 自身配置门控**的导入期引导，且**两个集成均默认关闭**：仅当集成显式启用且插件已安装时才 require。

  • Prometheus：nonebot_plugin_prometheus 通过 @driver.on_startup 挂载 /metrics 路由，必须在启动阶段被消费前注册。htmlrender 在导入阶段按 prometheus_enable（默认关闭，需显式 true）+ 安装状态引导，启用时端点如期挂载、指标可被抓取。
  • Sentry：nonebot_plugin_sentry 导入即 sentry_sdk.init()，htmlrender 在导入阶段按是否配置了 sentry_dsn（默认未配置即关闭）来引导。

需要主动迁移的点：

  • Prometheus 默认翻转为关闭。v0.7.1 只要装了插件就默认启用并暴露 /metrics；v0.7.2 起必须显式设 prometheus_enable=true 才会引导端点与记录指标。依赖旧默认的部署需补上该配置。
  • 若你此前依赖「装了但通过配置关闭仍被加载」这一副作用，也需调整为显式启用。

升级验收清单

  • 远程 render_text 与普通/数学 Markdown 不出现 Bot 侧 file:// 导航；
  • Markdown 相对图片按 Markdown 文件目录解析；
  • 自定义 CSS 的字体和背景图按 CSS 文件目录解析；
  • 动态 startup_render(endpoint=...) 与静态 WS/CDP 配置行为一致；
  • 共享卷部署已显式选择 passthrough，filehost 部署已显式选择 filehost；
  • 依赖页面导航的代码已从 base_url 迁移到 document_url；
  • Takumi 内容不包含 JS、网络资源或条件 stylesheet；
  • 不再导入未发布的模板 Path 常量或 PreparedHtml.markup；
  • 依赖 Prometheus 的部署已显式设 prometheus_enable=true（默认已关闭），/metrics 端点正常挂载。

更多历史背景见 远程 Playwright 部署、Takumi 配置 与 资源管线。