# iv8 **Repository Path**: hobinleon/iv8 ## Basic Information - **Project Name**: iv8 - **Description**: iv8 — Python 原生的 V8 + 浏览器环境运行时 - **Primary Language**: Python - **License**: Not specified - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-05-22 - **Last Updated**: 2026-05-22 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # iv8 — Python 原生的 V8 + 浏览器环境运行时 ## [English](./README_EN.md) | 中文 [![PyPI](https://img.shields.io/pypi/v/iv8)](https://pypi.org/project/iv8/) [![Python](https://img.shields.io/pypi/pyversions/iv8)](https://pypi.org/project/iv8/) [![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux-blue)]() [![GitHub](https://img.shields.io/badge/GitHub-iv8-blue?logo=github)](https://github.com/HanZzzzz000/iv8) **iv8** 是基于 V8 引擎的高性能 Python 原生扩展，在 C++ 层实现浏览器 API，提供高可控、高保真的 BOM/DOM/CSSOM 模拟，内置 API 调用链监控与 Chrome DevTools 远程调试，可在 Python 中直接运行依赖 Web 环境的 JavaScript，无需启动浏览器。适用于浏览器环境模拟、自动化脚本执行、安全研究、JS 引擎测试等场景。本仓库为 iv8 **社区版**，提供可用的基础浏览器环境模拟能力，能够满足绝大多数日常使用场景。 iv8 同时提供 **Pro 版**，在社区版基础上新增 CSS 布局引擎（级联、继承、盒模型布局）、CSS 动画与过渡驱动、基于 Chromium 网络模块深度裁剪的协议栈（非 Cronet 封装）、多上下文 Worker 并行执行、API 语义 / 时序 / 边界对齐增强（覆盖更多 spec 边界场景），以及计算性能、内存占用的深度算法优化。社区版持续迭代，Pro 版成熟特性将逐步回流至社区版。 Python 与 V8 的互操作层参考了 [STPyV8](https://github.com/cloudflare/stpyv8) 的设计思路，在此基础上优化设计与实现。 --- ## 核心亮点 | 特性 | 说明 | |------|------| | **C++ 原生浏览器 API** | 纯 C++ 实现 BOM / DOM / CSSOM / 事件 / 加密 / Canvas / WebGL 等标准接口，覆盖 70+ HTML 元素、25+ CSS 规则、80+ 事件类型 | | **流式 HTML 解析** | `page.load` 对齐浏览器导航流程：HTML 解析 → `', resources: { 'https://example.com/app.js': { body: 'window.APP_LOADED = true;' } } }); """) print(ctx.eval("window.APP_LOADED")) # True ``` ### 4. 事件循环与定时器控制实现微任务 / 宏任务两阶段调度（对齐 HTML spec event loop），宏任务按优先级分级，提供精细的时间控制 API。 - **宏任务**: setTimeout、setInterval、requestAnimationFrame、XHR/fetch 回调等 - **微任务**: Promise.then/catch/finally、queueMicrotask、MutationObserver 回调等 ```python with iv8.JSContext(time_mode="logical") as ctx: ctx.eval(""" var log = []; setTimeout(() => log.push('macro-100'), 100); setTimeout(() => log.push('macro-200'), 200); Promise.resolve().then(() => log.push('micro')); queueMicrotask(() => log.push('micro-2')); """) ctx.eval("window.__iv8__.eventLoop.advance(250)") print(ctx.eval("log")) # ['micro', 'micro-2', 'macro-100', 'macro-200'] ``` **事件循环控制方法：** | 方法 | 说明 | |------|------| | `advance(total, step?)` | 分帧推进虚拟时间（默认步长 ~16.67ms），模拟 rAF 节奏 | | `sleep(ms?, max?)` | 推进虚拟时间 ms 毫秒，按时间线顺序排空任务队列 | | `tick(ms?)` | 推进 ms 毫秒并执行一轮事件循环 | | `drain(max?)` | 排空所有已到期任务，不推进时间 | | `drainMicrotasks()` | 仅排空微任务队列 | | `drainTimers()` | 仅处理已到期的定时器回调 | | `setAutoAdvanceStep(ms)` | 设置 `performance.now()` 自动递增量（默认 0.001ms） | | `setDateAdvanceStep(ms)` | 设置 `Date.now()` 自动递增量（默认 1ms） | **时间模式：** | 模式 | 说明 | 适用场景 | |------|------|---------| | `logical`（默认） | 纯逻辑推进，`sleep(5000)` 瞬间完成 | 自动化、快速执行 | | `system` | 系统时间锚定，JS 执行期间 Date.now() 反映真实耗时 | 时间敏感场景（POW、时间差校验） | ### 5. 网络请求拦截 > **社区版网络边界：** 社区版不直接发起真实 HTTP/HTTPS 请求，也不内置 Chromium 网络传输栈。XHR / fetch / 外联资源默认从离线 bundle 匹配响应；真实请求需由 Python 侧 HTTP 客户端完成，再通过 `add_resource()` 或 `page.load.resources` 注入。Pro 版提供基于 Chromium net 深度裁剪的真实网络协议栈。 `add_resource()` 和 `page.load` 的 `resources` 参数写入同一个离线资源 bundle， HTML 解析期的 `