Playwright 配置¶

配置项默认值（代码基准）¶

以下默认值以当前代码实现为准（nonebot_plugin_htmlrender/backend/playwright/config.py）。

启动与连接¶

资源解析与 filehost¶

归一化与校验规则¶

• connect_ws.endpoint 与 connect_cdp.endpoint 不能同时配置。
• connect_cdp.endpoint 只允许搭配 engine=chromium。
• channel 只允许在 engine=chromium 时配置。
• executable_path 传空字符串或 . 会被归一化为 null。
• filehost_allowed_paths / filehost_prewarm_paths 传单个字符串时会自动转为列表。
• filehost_prewarm_extensions 支持逗号分隔字符串，会自动补 .、转小写、去重并保持顺序。
• filehost_request_header_name 传空白字符串会回退到默认值。
• filehost_request_header_value 传空白字符串会回退为 null（表示自动派生 token）。
• filehost_request_header_salt 传空白字符串会回退到默认值。

filehost 缓存行为¶

启用 filehost 解析后，插件会在进程内对**文件路径**类型的资源做去重缓存，避免同一文件被反复上传：

• 命中条件：绝对路径相同、且 mtime/size 都未变化。文件被覆盖（即使路径名相同）会立刻触发重新上传。
• TTL：由 filehost_cache_ttl_seconds（默认 300 秒）控制；每次命中刷新过期时间，长时间未访问的条目会被驱逐。
• 租约保护：单次 render_template 期间用到的资源会被钉住直至该次渲染结束，不会因并发请求的 TTL 检查被抢先驱逐——即使 TTL 设得很短也不影响渲染正确性。
• 并发去重：同一文件被多个并发渲染同时引用时，只会触发一次 filehost 上传，其他请求等待复用。
• bytes/BytesIO 不走缓存：因为没有稳定 key，每次都重新调用 FileHost(...).to_url()。如果你大量渲染依赖二进制资源且看到 filehost 调用过多，请改成把数据落盘后再传 Path。

实现细节与公共 API（prune_filehost_cache() 等）参见维护者文档的「Filehost 缓存与租约」一节：Filehost 资源解析方案。

本地启动配置¶

render_playwright.engine

浏览器引擎类型。
参考：Playwright Browsers

render_playwright.channel

Chromium channel（仅 engine=chromium）。
参考：BrowserType.launch(channel)

render_playwright.executable_path

指定浏览器可执行文件路径。
参考：BrowserType.launch(executable_path)

render_playwright.launch_args

附加浏览器启动参数。
参考：BrowserType.launch(args)

render_playwright.proxy_server / render_playwright.proxy_bypass

浏览器代理与绕过规则。
参考：BrowserType.launch(proxy)

render_playwright.cleanup_legacy_cache

是否自动清理旧版默认缓存目录（如 ~/Library/Caches/ms-playwright）。默认仅告警不删除；显式设为 true 后，插件会在启动阶段发现 legacy 目录时自动清理。

远程连接配置¶

远程渲染分为两类：远程 Playwright（WS）与远程浏览器（CDP）。

远程 Playwright（WS）¶

render_playwright.connect_ws.endpoint

Playwright WS 连接地址。
参考：BrowserType.connect

RENDER_PLAYWRIGHT={"engine":"chromium","connect_ws":{"endpoint":"ws://127.0.0.1:3000/"}}

import nonebot

nonebot.init(
    render_playwright={
        "engine": "chromium",
        "connect_ws": {"endpoint": "ws://127.0.0.1:3000/"},
    }
)

远程浏览器（CDP）¶

render_playwright.connect_cdp.endpoint

Chromium CDP 连接地址。
参考：BrowserType.connect_over_cdp

RENDER_PLAYWRIGHT={"engine":"chromium","connect_cdp":{"endpoint":"http://127.0.0.1:9222/"}}

import nonebot

nonebot.init(
    render_playwright={
        "engine": "chromium",
        "connect_cdp": {"endpoint": "http://127.0.0.1:9222/"},
    }
)

WS / CDP 差异¶

资源解析配置¶

render_playwright.resource_resolve_mode

off / auto / strict

render_playwright.remote_local_resource_policy

passthrough / filehost / error

render_playwright.local_local_resource_policy

file / filehost / passthrough

Filehost 安全配置¶

render_playwright.filehost_allow_any_path

是否允许 filehost 暴露任意本地路径。默认 false（推荐保持默认）。

render_playwright.filehost_allowed_paths

filehost 额外允许暴露的本地目录白名单（绝对/相对路径均可）。
未命中白名单且不在模板目录下的路径会被拒绝。

render_playwright.filehost_request_header_name

filehost 资源请求校验用 header 名。默认 X-HTMLRender-Filehost-Request。

render_playwright.filehost_request_header_value

filehost 资源请求校验 token。
配置后将直接使用该值，覆盖自动派生逻辑。

render_playwright.filehost_request_header_salt

filehost 自动派生 token 的盐值。默认 nonebot-plugin-htmlrender:filehost:guard:v1。
仅在 filehost_request_header_value 未配置时生效。