企业官网建设流程全解析

如何用 node-lynx CLI 在 Node.js 中渲染 Lynx bundle 并截取 headless 截图

【免费下载链接】lynxEmpower the Web community and invite more to build across platforms.项目地址: https://gitcode.com/GitHub_Trending/lynx10/lynx

当你需要在 Node.js 环境中把一个 Lynx bundle 渲染出来并拿到一张 PNG 截图（CI 校验、模板快速验证、自动化测试）时，Lynx 仓库中的@lynx-js/node-lynx包提供了node-lynxCLI：它可以在无窗口（headless）模式下加载远程或本地 bundle，渲染出首帧后写入 PNG 文件。当前包版本为0.1.3，随包提供的平台原生包覆盖darwin-arm64与linux-x64（见 package.json）。本文基于 oliver/node-lynx/README.md 与 skills/node-lynx/SKILL.md 整理出完整的截图操作路径。

安装并确认 CLI 可用

在需要截图的项目目录中安装：

npm i @lynx-js/node-lynx

安装后会得到node-lynx命令。包的说明指出，它会从匹配的可选平台包（例如@lynx-js/node-lynx-darwin-arm64）加载原生 addon；在仓库内开发时则从本地build/或platform/目录加载。

用 help 输出确认 CLI 已就位：

node-lynx --help

输出会列出render/preview两种模式以及-t, --template、-u, --url、-o, --output、-w, --width、--height、--dpr、--timeout、--screenshot-delay、--no-debug-router等选项（选项解析与默认值实现在 cli-main.ts 中，可对照查看）。

用远程 bundle URL 截取 headless 截图

文档给出的默认示例模板是https://lynxjs.org/lynx-examples/gallery/dist/GalleryComplete.lynx.bundle。一条完整的主路径命令：

node-lynx render \ "https://lynxjs.org/lynx-examples/gallery/dist/GalleryComplete.lynx.bundle" \ --width 268 \ --height 469 \ --dpr 2 \ --output ./gallery.png \ --timeout 30000 \ --screenshot-delay 500 \ --no-debug-router

各参数按文档的约定理解：

• 位置参数以http://或https://开头时，CLI 自动按远程 bundle URL 处理，无需再写--url。
• --width/--height是 CSS 像素视口值，默认分别为390和844。
• --dpr（或--device-pixel-ratio）默认2；输出 PNG 的像素尺寸是width * dpr乘以height * dpr，上面的参数组合会得到一张536 x 938像素的图。
• --output默认写到screenshot.png，父目录会被递归创建。
• --timeout <ms>覆盖 bundle 下载、模板加载、CDP 调用和首帧提交的等待上限，默认10000；网络较慢或 bundle 较重时调大。
• --screenshot-delay <ms>在首帧提交后、真正截图前额外等待，默认100，可以是0。
• --no-debug-router用于一次性截图：不加它时，render写完 PNG 后不会退出，而是等待SIGINT/SIGTERM以保持 DebugRouter 可用。CI 或脚本里做单次截图必须带上它；且它要求提供模板输入，否则会报missing Lynx bundle path or URL。

渲染本地 Lynx bundle

本地 bundle 用--template <path>传入，例如：

node-lynx render \ --template ./dist/main/template.js \ --width 390 \ --height 844 \ --output ./node-lynx-local.png \ --no-debug-router

CLI 内部会把本地文件读成 buffer，并以该文件路径生成的file://URL 作为模板 URL 传给loadTemplate（见 cli-main.ts 中loadTemplateSourceIntoView）。如果 bundle 中使用了 URL 相对路径的资源，文档建议直接传一个真实的远程模板 URL，让相对资源有正确的解析基准。

验证截图结果

判断一次截图是否成功，看两点：

1. 进程输出：render写图后会打印Headless Lynx screenshot written to: <输出路径>；带--no-debug-router时打印后进程直接退出，脚本可以据此继续。
2. PNG 文件与尺寸：检查输出文件存在，并且像素尺寸等于width * dpr与height * dpr的乘积（如268/469/dpr 2对应536 x 938）。

仓库自带一条可执行的验证路径：test/render_gallery.js 通过HeadlessLynxView加载同一 gallery 模板（width 268 / height 469 / devicePixelRatio 2 / timeoutMs 30000），断言截图尺寸为536 x 938，并对像素内容做采样检查。在仓库根目录可以这样跑：

pnpm --filter @lynx-js/node-lynx run test:gallery

该脚本默认把结果写到系统临时目录下的node-lynx-gallery-validation/（headless.png与summary.json），也支持传一个输出目录作为第一个参数；等待时长可用环境变量NODE_LYNX_GALLERY_MIN_WAIT_MS（默认2000）与NODE_LYNX_GALLERY_SETTLE_MS（默认3000）调整。它需要能访问上面的远程 gallery bundle。

截图时机与日志

文档对waitForFrame()的含义有明确限定：它只表示“一帧已提交”，并不保证所有图片或网络资源都已解码。因此对图片较多的页面，CLI 上应使用更大的--screenshot-delay（API 上对应screenshot({ settleMs })），或在页面提供了 ready 信号时等待该信号再截图。

如果截图命令的输出被 Lynx 日志淹没，可以用--log-level error隐藏 verbose、debug、info、warning 级别的 Lynx 日志，或--log-level silent隐藏全部输出；不传时保持 Lynx 默认级别。合法取值还有verbose、debug、info、warning、fatal。

限制与边界

• render是全平台可用的 headless 截图模式；preview是 macOS 专属的可视化窗口模式（AppKit 窗口），本文的截图任务不需要它。
• 不带--no-debug-router时，render写完 PNG 会挂起等待SIGINT/SIGTERM；不带任何模板输入时，render则进入等待 DebugRouter OpenCard 的状态，不会产出 PNG——所以“无模板 +--no-debug-router”不是合法组合。
• 需要 DebugRouter 时用--debug-router-schema <schema>显式指定连接 schema。

更多 API 形态（HeadlessLynxView编程式截图、CDP 检查）见 oliver/node-lynx/README.md 的 Headless API 章节；改动 CLI 或包本身时，仓库根目录的pnpm --filter @lynx-js/node-lynx run test与tsc --noEmit是配套的校验命令。

【免费下载链接】lynxEmpower the Web community and invite more to build across platforms.项目地址: https://gitcode.com/GitHub_Trending/lynx10/lynx