iv8 是一个 Python 原生的 V8 + 浏览器环境运行时，其核心 APIpage.load能以流式 HTML 解析方式模拟真实浏览器的导航流程：按块解析 HTML、暂停执行<script>脚本、处理样式表，并依次派发DOMContentLoaded/load等生命周期事件。对于需要在 Python 中运行依赖页面生命周期的 JavaScript（如指纹检测、反爬逻辑）的场景，这是最贴近真实浏览器行为的加载方式。

图：iv8 系统级运行模型，每个 JSContext 独占一个 V8 Isolate，Document runtime 负责 HTML 生命周期（page.load 加载流程）与事件循环

1️⃣ 为什么需要"浏览器级"的页面加载

很多 JavaScript 并非"一执行完就结束"，它们会：

• 监听DOMContentLoaded或window.load事件后再初始化；
• 依赖外联<script src>的执行顺序；
• 检查document.URL、location.href与页面是否一致。

如果用innerHTML = html直接赋值，iv8 只会构建 DOM 树：不执行脚本、不派发事件、不同步 URL，页面 JS 的初始化逻辑很可能永远不会被触发。

而page.load(snapshot)完整对齐了浏览器的关键导航阶段：

HTML 流式解析 →<script>暂停并执行 →<style>/<link>样式表处理 → DOMContentLoaded / load 事件派发 → 同步 document.URL / location.href

这正是它的核心价值：让目标 JS"以为"自己正运行在真实浏览器的页面加载过程中。

2️⃣ 30 秒上手：安装与第一次 page.load

支持 Python 3.9–3.14，Windows / Linux（aarch64 也支持），macOS 实验性支持。

pip install --upgrade iv8 -i https://pypi.org/simple

最小示例（来自 README.md）：

import iv8 with iv8.JSContext() as ctx: ctx.eval(""" window.__iv8__.page.load({ baseURL: 'https://example.com', html: '<html><body><div id="app">Hello</div></body></html>' }); """) print(ctx.eval("document.getElementById('app').textContent")) # "Hello"

注意page.load在 JS 侧的入口是window.__iv8__.page.load(...)，该工具对象对目标 JS"不可见"（typeof window.__iv8__ === "undefined"），不会污染环境。

3️⃣ page.load 的 4 个核心参数速查

resources支持简写与完整两种格式：

resources: { 'https://example.com/lib.js': 'var LIB = true;', // 简写：直接给内容 'https://example.com/app.js': { // 完整格式：可带状态码/响应头 body: 'var APP = true;', status: 200, headers: [['content-type', 'application/javascript']] } }

💡page.load的resources与 Python 侧的ctx.add_resource()写入的是同一个离线资源 bundle，HTML 解析期的外联脚本和运行期的 XHR / fetch 都会命中它，详见 demos/network_intercept.py。

4️⃣ 生命周期事件模拟：脚本执行的完整顺序

这是page.load最容易被忽视、也最有用的能力。下面的示例（完整版本见 demos/dom_pageload.py 第 6 节）记录了事件触发顺序：

with iv8.JSContext() as ctx: ctx.eval(""" window.__iv8__.page.load({ baseURL: 'https://example.com', html: `<!DOCTYPE html> <html><head> <script> window.LOG = []; document.addEventListener('DOMContentLoaded', () => window.LOG.push('DOMContentLoaded')); window.addEventListener('load', () => window.LOG.push('load')); window.LOG.push('script-executed'); </script> </head><body><div id="app">Content</div></body></html>` }); """) print(ctx.eval("window.LOG", to_py=True)) # ['script-executed', 'DOMContentLoaded', 'load']

几个关键点：

• 遇到<script>会暂停解析并执行，内联脚本和外联脚本都能按文档顺序运行；
• DOMContentLoaded在所有解析期脚本执行完毕后派发，load事件在其之后；
• 加载完成后document.URL与location.href会同步为baseURL，外联脚本执行失败不会打断流程；
• 0.1.3 起，解析期内联脚本中的document.write()写入的 DOM 也会持久化到文档树。

如果页面 JS 里还有setTimeout/ 异步回调，配合逻辑时间模式可瞬间推进，例如window.__iv8__.eventLoop.drain()，更多玩法见 demos/event_loop.py。

5️⃣ 如何选择：page.load vs innerHTML？

经验法则：目标 JS 不依赖DOMContentLoaded/load事件和外联脚本时，用innerHTML更省；只要涉及"页面行为"，就用page.load。

性能参考（README 实测）：~440 KB 的真实维基百科页面 DOM 解析约7 ms/页，Context 创建+销毁后总计约 11.5 ms，串行约 86 页/秒——在 Python 脚本里跑完整"页面加载"几乎没有感知成本。

6️⃣ 实用技巧与进阶

• 带资源加载验证外联脚本执行顺序：给resources注入多个<script src>，检查后执行脚本能否读取前者的全局变量，确认顺序对齐浏览器；
• 携带响应头：headers参数可以模拟content-type、CSP 等主文档响应头，贴近真实导航环境；
• 排查环境问题：用iv8.JSContext(mode='debug')开启 API 调用链监控，能自动记录目标 JS 读取了哪些浏览器 API（如navigator.userAgent），配合 DevTools 远程调试定位指纹检测逻辑，示例见 demos/devtools.py；
• 全量配置组合：指纹 + 环境 + page.load 一起用的完整示例见 demos/full_configuration.py。

小结

iv8 的page.load用一次调用就补齐了"浏览器页面加载"最难模拟的部分：流式解析、脚本暂停执行、样式表处理、生命周期事件派发与 URL 同步。只需baseURL+html两个参数即可起步，resources/headers按需增强，再配合可编程事件循环，就能在 Python 中以接近零成本复现一个"会跑脚本、会触发事件"的真实页面环境。