星外之神 Blog

LinSYS2：无需虚拟机与容器，在Linux上完整管理、构建、调试与运行Windows程序

Mon, 27 Apr 2026 00:00:00 +0000

前言

在Linux上为Windows平台开发程序，现有方案各有各的痛点：交叉编译装的是Linux移植版工具链，构建行为与Windows原生环境未必一致，编译出的二进制既无法运行也无法调试；虚拟机资源占用大、启动慢、与宿主交互割裂；容器方案则由于Wine上游不支持非原生的依赖msys-2.0.dll的程序，需要非标准的Wine fork，长期维护性存疑。

有没有一种方案，像交叉编译一样轻量、像虚拟机一样完整，同时只依赖上游普通Wine就能工作？

笔者开发的LinSYS2正是为此而生。它直接在Linux上安装来自MSYS2官方仓库的Windows原生工具链和库，通过Wine运行。两条命令，你就能在Linux shell里用上Windows版的GCC、GDB、CMake等程序——编译、调试、运行，全部在Linux下完成。

No VM. No dual-boot. No containers.

LinSYS2是什么

LinSYS2是能在Linux上自动安装、管理Windows工具链和依赖库的命令行工具。它在Linux端原生运行一个适配后的MSYS2 pacman fork，接入MSYS2官方仓库，将mingw-w64系列的Windows原生二进制包安装到用户目录下，随后你便可以像在Linux里调用普通命令一样，借助Wine运行这些Windows程序。

LinSYS2的核心是在Linux上使用Linux原生的pacman fork管理整个MSYS2的mingw-w64官方包生态，安装真正的Windows工具链后通过Wine运行Windows程序。它不提供模拟层，不维护独立的包集合，不fork上游仓库——它只是把MSYS2已经做好的工作，搬到了Linux桌面上。

这意味着：

你安装的工具链都是Windows原生版本，构建行为与Windows完全一致
你链接的库与Windows上通过MSYS2安装的库完全相同，版本、补丁、编译选项一致
通过Wine运行程序，启动速度接近原生，资源占用极低

核心特性一览

特性	说明
真正的Windows工具链	安装的是MSYS2官方仓库中的Windows版GCC/LLVM、GDB/LLDB、CMake/Meson等
完整的开发生命周期	安装包、编译代码、调试程序、运行测试、发布二进制，全部在Linux shell中完成
无需虚拟机与容器	通过Wine运行，启动速度接近原生，资源占用极低
用户级完全隔离	所有数据存储在`~/.local/share/linsys2/`，无需root，不污染系统，默认不污染`~/.wine`
多架构目标支持	单台机器可同时维护`ucrt64`（GCC/x86_64）、`clang64`（Clang/x86_64）、`clangarm64`（Clang/ARM64）环境
原生包管理体验	直接使用MSYS2 pacman，数万mingw-w64包即装即用，自动处理依赖

安装

Arch Linux

LinSYS2已发布到AUR，Arch Linux用户可以直接安装：

# 使用yay
yay -S linsys2

# 或使用paru
paru -S linsys2

AUR包通过GitHub Actions自动构建并发布，始终与主分支同步更新。

其他发行版

其他Linux发行版用户需要先安装对应的依赖包。各发行版的包名略有不同，以Debian/Ubuntu和Fedora为例：

Debian/Ubuntu：

sudo apt install meson ninja-build gcc make git patch pkg-config \
    libarchive-dev libssl-dev libgpgme-dev libcurl4-openssl-dev \
    gawk gettext which gnupg wine python3

Fedora：

sudo dnf install meson ninja-build gcc make git patch pkg-config \
    libarchive-devel openssl-devel gpgme-devel libcurl-devel \
    gawk gettext which gnupg wine python3

其中，构建依赖为：meson、ninja-build、gcc、make、git、patch、pkg-config以及libarchive、libssl、libgpgme、libcurl的开发包；运行时依赖为：bash、coreutils、gawk、grep、gettext、which、curl、gnupg、openssl、libarchive、bzip2、xz、zstd、wine和python。不需要任何特殊补丁或定制版本的Wine，发行版自带的普通Wine即可正常工作。

安装依赖后，通过源码编译安装：

git clone --recursive https://github.com/wszqkzqk/LinSYS2.git
cd LinSYS2
make && sudo make PREFIX=/usr install

快速上手：两条命令开始Windows开发

LinSYS2的安装和使用都极为简洁：

# 安装Windows版GCC
linsys2-pacman -Sy mingw-w64-ucrt-x86_64-gcc

# 运行它
linsys2 run -- gcc -v

只需两条命令，你就能在Linux上编译并运行Windows程序。linsys2-pacman会自动初始化环境、同步MSYS2官方数据库、安装包；linsys2 run会在隔离的Wine前缀中运行Windows GCC，输出与你直接在Windows MSYS2终端中运行gcc -v完全一致的信息。

典型工作流

初始化环境与同步数据库

linsys2-pacman -Syu

这与在Arch Linux或MSYS2中使用pacman -Syu的体验完全一致。LinSYS2会自动创建隔离的GPG keyring、配置文件和数据目录。

安装开发工具链

# GCC工具链
linsys2-pacman -Sy mingw-w64-ucrt-x86_64-gcc mingw-w64-ucrt-x86_64-gdb

# CMake
linsys2-pacman -Sy mingw-w64-ucrt-x86_64-cmake

# Python
linsys2-pacman -Sy mingw-w64-ucrt-x86_64-python

linsys2-pacman完整支持pacman的命令行接口：-S安装、-R卸载、-Ss搜索、-Q查询已安装包、-Syu全系统升级。所有命令都与pacman原生行为一致，无需重新学习。

编译与调试

# 编译Windows可执行文件
linsys2 run -- gcc -o app.exe app.c

# 用Windows GDB调试
linsys2 run -- gdb app.exe

# CMake构建
linsys2 run -- cmake -B build -S .
linsys2 run -- cmake --build build

linsys2 run使用隔离的Wine前缀（位于~/.local/share/linsys2/{env}/wine），通过WINEPATH环境变量动态注入bin目录和DLL搜索路径。这意味着：

无需手动配置Wine，即开即用
不修改任何注册表，环境完全无状态
不污染你现有的~/.wine，与日常运行其他Windows软件互不干扰

交互式Shell

如果你需要频繁使用多个Windows工具，可以进入交互式子shell：

linsys2 shell
# 现在所有Windows工具都在PATH中（但注意在Shell中运行时需要加上后缀名）
gcc.exe --version
gdb.exe --version
cmake.exe --version
cmd.exe

多环境切换

LinSYS2同时支持三种mingw-w64环境：

环境名	编译器	默认目标架构	包前缀
`ucrt64`	GCC (UCRT)	x86_64	`mingw-w64-ucrt-x86_64`
`clang64`	Clang (UCRT)	—	`mingw-w64-clang-x86_64`
`clangarm64`	Clang (UCRT)	ARM64	`mingw-w64-clang-aarch64`

默认环境根据主机CPU架构自动检测（x86_64默认ucrt64，ARM64默认clangarm64），也可通过--env参数显式指定：

linsys2-pacman --env clang64 -S mingw-w64-clang-x86_64-llvm
linsys2 run --env clang64 -- clang -v

与现有Wine集成

如果你已经在Linux上使用Wine运行其他Windows软件，并且不愿意再创建额外的Wine环境，也可以选择将LinSYS2环境注册到现有Wine前缀中：

linsys2 register    # 将LinSYS2的相关目录添加到Wine注册表PATH
linsys2 env         # 查看注册状态
linsys2 unregister  # 从Wine PATH中移除

技术实现要点

为什么必须使用MSYS2 pacman fork

MSYS2维护了一个pacman的fork，其中包含34个补丁。LinSYS2无法直接使用Arch Linux自带的pacman，原因只有一个：epoch分隔符。

在Arch Linux中，软件包的epoch（当版本号 scheme 变更时用于强制升级的前缀）使用冒号:分隔，例如1:2.0-1。但Windows文件名不能包含:，因此MSYS2将epoch分隔符改为波浪号~，格式为1~2.0-1。MSYS2的第13号补丁正是修改了这一行为：

// lib/libalpm/version.c
#if defined(__MSYS__) || defined(MSYS2_PACMAN_LINUX)
    if(*s == '~') {  // MSYS2 使用 ~ 分隔 epoch
#else
    if(*s == ':') {  // Arch 使用 : 分隔 epoch
#endif

MSYS2官方仓库中存在大量使用~作为epoch分隔符的包。如果Linux端使用原生pacman（期望:），这些包的版本号将无法被正确解析和比较，导致数据库同步失败、依赖解析错乱、安装命令无法匹配包名。因此，必须在Linux下构建MSYS2的pacman fork，这是不可回避的技术前提。

LinSYS2的解决方案非常精巧：通过一个统一的补丁（patches/0001-LinSYS2-Adapt-MSYS2-pacman-for-Linux.patch），将MSYS2 fork中所有关键的#ifdef __MSYS__条件编译扩展为#if defined(__MSYS__) || defined(MSYS2_PACMAN_LINUX)，同时在meson构建时通过-DMSYS2_PACMAN_LINUX宏启用这些代码路径。这样，MSYS2 fork中绝大多数适配逻辑在Linux构建时自动生效。

patches/0001-LinSYS2-Adapt-MSYS2-pacman-for-Linux.patch处理了以下关键差异：

epoch分隔符：启用~分隔符，使版本解析与MSYS2仓库兼容
权限模型：跳过root权限检查，支持普通用户运行（RootDir设在用户目录下）
文件提取权限：非root用户跳过ARCHIVE_EXTRACT_OWNER，避免权限错误
工具路径固定：在$MSYS2_PACMAN_LINUX环境下使用固定工具路径，避免与系统工具冲突
CR处理：从stdin读取时正确处理\r\n换行符

包格式与数据库的跨平台兼容性

LinSYS2能够直接复用MSYS2官方仓库，还得益于：

数据库层100%兼容：MSYS2与Arch Linux使用完全相同的ALPM数据库格式（版本9）。pacman的desc/files/mtree文件结构、tar归档格式、PGP签名机制在Linux下可直接读写，无需任何转换。
包格式层100%兼容：mingw-w64包就是标准的.pkg.tar.zst（libarchive格式），pacman的提取过程是纯文件解压操作，完全不涉及任何Windows API，也不关心包内文件是ELF还是PE。
依赖解析层100%兼容：pacman的依赖解析是纯字符串匹配，只比较包名和版本号，从不检查包内文件的实际格式。这意味着mingw-w64包的依赖关系在Linux端可以被完美解析和处理。
架构字段无冲突：mingw-w64包的arch字段通常为any，与Linux主机的x86_64或aarch64不会产生冲突。

因此，LinSYS2能够在Linux上直接使用MSYS2的包管理系统，安装和管理Windows原生工具链和库，而几乎无需特殊处理。

Wine前缀管理与环境注入策略

LinSYS2提供了两种Wine集成模式，以适应不同使用场景。

独立WINEPREFIX模式（默认推荐）

独立WINEPREFIX模式下每个环境拥有独立的Wine前缀（~/.local/share/linsys2/{env}/wine）。linsys2 run在运行程序前，会自动构造包含bin目录的WINEPATH环境变量传递给Wine。DLL搜索路径通过WINEPATH注入，不修改任何注册表键值。这种模式的优势在于：

与用户的日常Wine环境（~/.wine）彻底隔离，避免任何潜在的冲突或污染
多个LinSYS2环境之间互不干扰
删除环境时只需删除对应目录，无残留

现有Wine环境集成

使用linsys2 register，将环境bin目录写入现有Wine前缀的注册表PATH中可以实现在现有Wine环境中集成LinSYS2。对于不希望额外创建单独Wine前缀的用户，这种模式提供了更直接的集成方式，可以将现有Wine环境下的内容直接和LinSYS2集成。

无论哪种模式，LinSYS2都会自动处理Windows路径与Unix路径的转换，在从LinSYS2中运行时还会禁用winemenubuilder.exe以避免污染桌面菜单和MIME关联。

用户级隔离与零系统冲突

LinSYS2仅在用户目录下进行安装和管理：

数据目录：~/.local/share/linsys2/{env}/，存放实际安装的文件、包数据库和缓存
配置目录：~/.config/linsys2/，存放各环境独立的pacman配置文件和镜像列表
Wine前缀：~/.local/share/linsys2/{env}/wine/，独立的Wine环境
GPG keyring：每个环境拥有独立的etc/pacman.d/gnupg/，互不干扰

这种设计下，安装和运行LinSYS2完全不需要root权限，也不会与系统的pacman包管理器产生任何冲突。你可以在Arch Linux上同时使用系统pacman管理软件包，用linsys2-pacman管理Windows工具链，两者分别存储，互不干扰。

`.install` Scriptlet与Hook的处理

mingw-w64包极少包含.install安装脚本（scriptlet），绝大多数是纯文件包。LinSYS2的默认策略是使用--noscriptlet跳过scriptlet执行，这既避免了Windows .exe安装脚本在Linux下无法直接运行的问题，也符合mingw-w64包的实际分布情况。

对于极少数确实需要scriptlet的包，LinSYS2的架构也预留了通过Wine代理执行的扩展空间。Hook脚本的情况类似——mingw-w64包几乎不使用pacman hook，因此当前实现中无需特别处理。

横向对比总结

为了更直观地展现LinSYS2的定位，笔者将几种常见方案做一个全面的横向对比：

维度	传统交叉编译	虚拟机（VM）	容器	LinSYS2
构建工具链来源	Linux发行版移植	Windows原生	Windows原生	MSYS2官方仓库的Windows原生工具链
构建行为一致性	可能与Windows不同	与Windows相同	与Windows相同	与Windows相同
运行生成的二进制文件	不能	能	能	能（通过Wine）
使用Windows GDB调试	不能	能	能	能
库文件来源	发行版打包	Windows安装	镜像内安装	MSYS2官方仓库，与Windows一致
包管理器	无或发行版方案	Windows/手动	手动配置	MSYS2 pacman（原生体验）
依赖自动解析	有限	手动	手动	完整自动依赖解析
启动速度	快	慢（需启动完整OS）	中等（需启动容器）	快（Wine近原生速度）
资源占用	低	高（数GB内存+磁盘）	中等（镜像体积大）	低（与Wine相当）
用户权限要求	通常需要root	需虚拟化支持	通常需要root	用户级，无需root
系统集成度	与系统深度集成	完全隔离	隔离	可选隔离或渐进式集成
环境管理	手动	手动	手动	多环境并行，一键切换

从表格中可以清晰看出，LinSYS2在轻量性上接近传统交叉编译，在功能完整性上媲美虚拟机，同时提供了原生的包管理体验——这在以往的所有方案中都是缺失的。

结语

LinSYS2的设计哲学非常简洁：不重复造轮子，把已经运转良好的生态桥接到新的平台。它不fork MSYS2的包仓库，不维护独立的工具链，不做任何对包内容的修改——它只是利用ALPM数据库的跨平台兼容性、pacman依赖解析的格式无关性，Wine对Windows PE程序的执行能力，以及pacman对Linux的原生支持，将这四者巧妙地串联起来。

对于需要在Linux上开发Windows应用程序的开发者而言，LinSYS2提供了一个轻量、高效、行为一致的解决方案。你无需离开熟悉的Linux开发环境，无需忍受虚拟机的臃肿，就能获得与Windows上完全相同的工具链和构建流程。

回顾笔者之前对Wine定位的思考，LinSYS2正是这种思路的延续：不再将Wine视为填补生态缺口的双刃剑，将Wine用作跨平台开发的基础设施。当开源开发者能如此便捷地在Linux下为Windows构建、调试、测试原生应用时，使用Linux的开发者将得以进一步减少对Windows的依赖，真正实现跨平台开发的无缝体验。

项目地址：https://github.com/wszqkzqk/LinSYS2
AUR地址：linsys2
开源协议：GPL v2 or later
AI文档与问答：https://deepwiki.com/wszqkzqk/LinSYS2

Qt Web Extractor：适配 Anubis 并与 Qt HTML 解析斗智斗勇

Mon, 20 Apr 2026 00:00:00 +0000

背景

Qt Web Extractor 最近遇到了两个比较复杂的问题：一个是 Anubis 反爬虫的 PoW 挑战页，另一个是 Qt QTextDocument 解析大页面 HTML 时的内存失控。排查下来发现，前者的修复其实非常简洁；后者虽然还没彻底解决，但恰好被前者的修复方式给自然缓解了。

Anubis：其实适配很简单

现象

笔者在测试提取 gitlab.winehq.org/wine/wine 时，发现返回的总是这段内容：

Making sure you’re not a bot!

Loading…

You are seeing this because the administrator of this website has set up Anubis to protect the server…

拿不到后面的真实 GitLab 内容。

分析

Anubis 是一种基于 PoW（Proof-of-Work）的反爬虫中间件。服务器向浏览器下发一个 SHA-256 计算挑战，客户端需要在本地通过 JavaScript brute-force 找出一个满足难度要求的 nonce，完成后通过 cookie 才能访问真实页面。

跟 Cloudflare 那种复杂的指纹识别和行为分析不同，Anubis 的核心逻辑其实非常直白：它就是要求你付出算力。对于真正的浏览器来说，这意味着在本地执行几秒的 JavaScript 计算。对于爬虫来说，这意味着大规模抓取的成本会急剧上升。

而 Qt Web Extractor 本身就是一个完整的 Chromium headless 环境，有完整的 JavaScript 引擎，执行 PoW 计算完全不在话下。实际上笔者观察过，Anubis 的 main.mjs 在 Qt WebEngine 中可以正常执行，PoW 计算和后续重定向都没有问题。

真正的问题在于提取器和 Anubis 的工作流没有对齐。

Qt Web Extractor 的流程是：

page.load(url) 加载页面
等 loadFinished 信号
loadFinished 后启动一个 2 秒的单发定时器
定时器触发后，注入 JavaScript 递归遍历 DOM，序列化成 HTML
_finish() 设置 settled = True，提取结束

Anubis 挑战页的初始 HTML 很小（约 4KB），loadFinished 在几百毫秒内就会触发。但此时页面上的 main.mjs 才刚刚开始执行 PoW 计算，整个计算过程需要几秒到十几秒。计算完成后 JavaScript 调用 window.location.replace() 重定向到真实页面，这会触发新的 loadStarted → loadFinished 周期。

但原来的代码只连接了 loadFinished，没有连接 loadStarted。所以 2 秒定时器触发后，提取器拿到当时的 DOM（挑战页），调用 _finish()，settled = True。这时候 Anubis 的 PoW 可能还在进行，甚至可能尚未启动。等几秒后 PoW 计算完成、页面重定向到真实内容、新的 loadFinished 触发——但 settled 已经是 True，所有后续处理都被跳过。真实页面就这样被忽略了。

也就是说，PoW 能够正常计算完成，重定向也会正常执行，但提取器在重定向触发之前就已经 settled，后续的真实内容完全没有机会进入提取流程。

修复

修复的思路是：既然提取器本身就能正常执行 PoW，那我们只需要等待计算完成即可。

window.location.replace() 会触发 loadStarted，这是感知自刷新的最直接方式。笔者在 _WebPage 中加了对 loadStarted 的连接：

self.loadFinished.connect(self._on_load_finished)
self.loadStarted.connect(self._on_load_started)

def _on_load_started(self):
    self._stability_timer.stop()

Anubis 完成 PoW 触发重定向时，旧的 stability timer 会被停止。随后真实页面加载完成触发新的 loadFinished，重新启动 2 秒倒计时，在真实页面稳定后才提取。

看 commit 记录就知道了——e993fec 这个 commit 只改了 5 行代码：加了一个 _on_load_started 方法、连接了 loadStarted 信号、修正了一个空白字符。Anubis 这种看似强力的反爬虫，对于一个本身就有完整 Chromium 内核的提取器来说，适配成本相当低。它不像 Cloudflare 那样需要绕过复杂的指纹识别，其核心只是要求客户端执行一段 JavaScript 计算。

修复后的行为是概率性的，取决于 PoW 计算时间和网络延迟的相对关系：

如果 PoW 在 2 秒定时器触发前完成，重定向发生时 timer 会被 loadStarted 重置，最终能成功提取真实页面。对于 winehq.org 这种难度较低的配置（PoW 约 2-3 秒），这种情况出现的概率很高，所以”大多数 Anubis 已经能够正常处理”。
如果 PoW 超过 2 秒，定时器先触发，提取器 settled，后续真实页面被忽略。kernel.org 的部分配置难度为 5，PoW 可能需要 5-8 秒，这种情况下会提取到挑战页。

笔者也尝试过延长 stability delay 到 5 秒或更长，让 PoW 有更充分的时间完成。但这个方向很快就被放弃了，原因跟下面要说的内存问题直接相关。

Qt HTML 解析的内存失控

现象

在测试提取 Linux 内核的一个大型 merge commit 时，Python 进程在提取阶段被系统 OOM killer 杀掉。同一个页面在 Chrome 和 Firefox 中打开完全正常，内存占用也就几百 MB。但通过 Qt Web Extractor 提取时，内存占用一路飙升到 30GB 以上，直到耗尽。

定位

问题出在 QTextDocument.setHtml()。

Qt Web Extractor 的提取管线中，HTML 到 Markdown 的转换依赖 QTextDocument：

doc = QTextDocument()
doc.setHtml(html)
md = doc.toMarkdown()

这个 commit 页面的 diff 内容非常大，cgit 用 <table> 展示 diff，每行一个 <tr>。浏览器渲染这种页面没有问题，因为浏览器的光栅化和布局是流式的。但 QTextDocument 是富文本处理类，内部会把 HTML 转换成块结构、表格结构和格式对象。对于包含数万行表格的代码 diff 页面，setHtml() 内部需要为每个单元格分配格式对象和布局元数据，内存膨胀非常严重。

笔者通过诊断脚本确认了规模：

body.innerHTML.length = 2057483
outer_html_len = 2058590
inner_text_len = 1171958

2MB 的原始 HTML 在 QTextDocument 中膨胀到 30GB 以上，这是 Qt 解析器的问题。QTextDocument 的设计目标是处理编辑器量级的富文本，不是作为通用的任意大小 HTML 解析器。

尝试与回退

笔者一度在 _text_from_html 中加入了大小阈值判断，对大页面降级为 innerText 提取，绕过 QTextDocument。但这样做其实是在掩盖问题，而不是解决它。而且 innerText 丢失了 Markdown 的超链接和表格结构，输出质量明显下降。

经过考虑，笔者回退了这个降级修改。2MB 的 HTML 不应该让任何解析器吃掉 30GB 内存，这是 Qt 的问题。在找到更根本的解决方案之前，不应该用降级来掩盖。

与大页面内存问题的交叉影响

这里有一个需要说明的情况。kernel commit 这种大页面，真实内容本身就很大（约 2MB HTML），一旦进入 Qt 解析路径就会 OOM。笔者测试过，如果延长 stability delay 到 5 秒或更长，给 Anubis 更充分的时间完成重定向，真实页面被提取后内存会直接爆掉。

保持 2 秒的 delay 反而避免了这个问题。这个巨大的页面在 2 秒内通常无法完成到真实页面的重定向。2 秒定时器触发后，提取器拿到 Anubis 挑战页（只有 4KB，安全），然后 settled。后续即使网络恢复、重定向到真实页面，由于 settled 已经是 True，真实大页面永远不会被提取——所以 Qt 解析大页面的 OOM 也永远不会触发。

换句话说，大页面的真实内容因为 Anubis 未完成而被跳过，但这也恰好绕过了 Qt 解析器的内存失控。这不是特意设计的保护机制，而是当前网络环境和 2 秒 delay 共同产生的实际效果。

目前的状态是小页面（如 gitlab.winehq.org/wine/wine）的 Anubis 流程顺畅，大概率能在 2 秒内完成重定向，能正常提取；大页面 Anubis 运算后在 2 秒内通常无法完成页面内容加载，提取到的是挑战页，真实内容拿不到，但至少不会 OOM。

内容丢失问题

在排查过程中，笔者还遇到了两个内容提取不完整的问题，修复方式各不相同。

checkVisibility 的误判

之前的 Shadow DOM flatten JS 中加入了这行：

if (node.checkVisibility && !node.checkVisibility()) return '';

意图是过滤掉不可见元素。但在某些现代网页中，checkVisibility() 会因为计算时机、CSS 动画状态或元素尚未进入 viewport 而返回 false，导致可见内容被错误过滤。笔者在测试 SemiAnalysis Newsletter 的一篇文章时，提取结果大量缺失——正文被全部过滤掉了。

修复是直接移除了这行（commit 948ed7a）。不可见元素的过滤应该属于内容处理的后续阶段，不应该在 DOM 序列化时做硬拦截。

DOM 遍历范围的遗漏

另一个问题出在 DOM 序列化的入口点上。原来的代码从 document.body 开始遍历：

return '<html><body>' + walk(document.body) + '</body></html>';

这导致某些页面的 head 内容无法被正确捕获，提取结果异常。笔者在测试 Google Open Source Blog 的一篇文章时，提取结果几乎只剩一个 1——正文结构完全丢失。

修复是将遍历入口改为 document.documentElement，并扩展 SKIP 集合以显式排除 meta、link、base、title 等标签（commit 8ca4503）：

const SKIP = new Set(['script','style','svg','noscript','template','meta','link','base','title']);
// ...
return walk(document.documentElement);

总结

目前代码中已提交的修复包括：

loadStarted 信号连接，在导航时重置 stability timer
移除了 checkVisibility 过滤
DOM 遍历入口从 document.body 改为 document.documentElement，并扩展 SKIP 标签集合

stability delay 保持 2 秒不变。Anubis 这种基于 PoW 的反爬虫系统，对于一个本身就有完整 Chromium 内核的 headless 提取器来说，适配成本非常低——它不需要绕过任何复杂检测，只需要等待 PoW 计算完成即可。整个核心修复只有几行代码。

Qt 的 QTextDocument 在处理大表格 HTML 时的内存失控，笔者已经确认是 Qt 侧的问题，需要进一步研究是 Qt 版本相关的已知问题，还是特定 HTML 结构触发的边缘情况。在找到可靠的修复或替代方案之前，这是项目的一个已知限制。而当前 2 秒的 delay 配置恰好避免了实际触发这个问题，算是一个意外的平衡。

项目仓库地址：GitHub · Qt Web Extractor

项目协议：GPL-3.0-or-later

PvZ-Portable：跨平台光标系统的 SDL 实现与自定义光标缓存

Thu, 16 Apr 2026 00:00:00 +0000

引言

在将 PvZ-Portable 从 Windows 原生引擎改造为跨平台项目的过程中，渲染、音频、输入等核心子系统都经历了大规模重构。但有一个看似不起眼的模块长期被搁置——光标系统。旧代码里，LawnApp::EnforceCursor() 中躺着一大段被注释掉的 ::SetCursor / LoadCursor Win32 API 调用，事实上，游戏此前一直并没有实现跨平台光标处理。

光标系统虽小，却是玩家与游戏交互的第一触点。当玩家悬停在可点击的按钮上时需要手型光标，在文本输入框中需要 I 形光标，在战斗场景中还需要隐藏光标以避免干扰沉浸感。本文将记录笔者如何彻底移除 Windows 专属的光标代码，在 SexyAppBase 中基于 SDL 实现一套完整的跨平台光标系统，并解决自定义光标创建与运行时缓存的技术细节。

被遗留的 Windows 光标实现

原版引擎的光标管理集中在 LawnApp 层，EnforceCursor() 是整个游戏的唯一光标控制入口。旧代码的典型模式如下(（被注释掉，没有实际生效）：

void LawnApp::EnforceCursor()
{
    if (mSEHOccured || !mMouseIn)
    {
        ::SetCursor(LoadCursor(nullptr, IDC_ARROW));
        return;
    }

    if (mOverrideCursor)
    {
        ::SetCursor(mOverrideCursor);
        return;
    }

    switch (mCursorNum)
    {
    case CURSOR_POINTER:
        ::SetCursor(LoadCursor(GetModuleHandle(nullptr), MAKEINTRESOURCE(IDC_CURSOR1)));
        return;
    case CURSOR_HAND:
        ::SetCursor(mHandCursor);
        return;
    // ... 更多 Windows 专属分支 ...
    }
}

这段代码有两大问题：

平台耦合过重：HCURSOR、LoadCursor、SetCursor、GetModuleHandle 全部是 Win32 API，无法在其他平台上编译或运行。
架构位置过高：光标作为通用窗口系统能力，本应由应用框架层（SexyAppBase）负责，而不应该由游戏逻辑层（LawnApp）持有。将光标控制放在 LawnApp 意味着每个基于该框架的新项目都要重复实现一遍。

在 PvZ-Portable 此前的版本中，这段代码一直处于被完全注释掉的状态，导致跨平台构建时虽然能编译通过，但光标行为是缺失的。

跨平台重构：下沉到 SexyAppBase

修复的第一步是把光标逻辑从 LawnApp 完全移除，转而在 SexyAppBase 中以 SDL API 重新实现 EnforceCursor()。这样，所有基于该框架的应用都能自动获得跨平台光标支持。

新的 EnforceCursor() 核心逻辑如下：

void SexyAppBase::EnforceCursor()
{
    int aCursorNum = mSEHOccured ? CURSOR_POINTER : mCursorNum;
    if (aCursorNum < 0 || aCursorNum >= NUM_CURSORS)
        aCursorNum = CURSOR_POINTER;

    if (aCursorNum == CURSOR_NONE)
    {
        SDL_ShowCursor(SDL_DISABLE);
        return;
    }

    SDL_Cursor* aCursor = nullptr;

    // 1. 优先使用自定义光标（如果启用且已设置图片）
    if (mCustomCursorsEnabled && mCursorImages[aCursorNum] != nullptr)
    {
        // ... 从 MemoryImage 创建或命中缓存 ...
    }

    // 2. 回退到系统光标
    if (aCursor == nullptr)
    {
        SDL_Cursor*& aCachedCursor = mSysCursors[aCursorNum];
        if (aCachedCursor == nullptr)
            aCachedCursor = SDL_CreateSystemCursor(CursorNumToSystemCursor(aCursorNum));
        aCursor = aCachedCursor;
        if (aCursor == nullptr)
            aCursor = SDL_GetDefaultCursor();
    }

    if (aCursor != nullptr)
        SDL_SetCursor(aCursor);

    SDL_ShowCursor(SDL_ENABLE);
}

这个结构清晰地划分了三个层级：自定义光标 → 系统光标 → 默认光标。CURSOR_NONE 则单独走隐藏分支，确保在任何平台下都能可靠地隐藏鼠标指针。

系统光标映射

SDL2 提供了一套与操作系统无关的系统光标枚举 SDL_SystemCursor。笔者编写了一个静态映射函数，将引擎内部使用的 CURSOR_xxx 枚举转换为对应的 SDL 枚举：

static SDL_SystemCursor CursorNumToSystemCursor(int theCursorNum)
{
    switch (theCursorNum)
    {
        case CURSOR_HAND:        return SDL_SYSTEM_CURSOR_HAND;
        case CURSOR_TEXT:        return SDL_SYSTEM_CURSOR_IBEAM;
        case CURSOR_CIRCLE_SLASH:return SDL_SYSTEM_CURSOR_NO;
        case CURSOR_SIZEALL:     return SDL_SYSTEM_CURSOR_SIZEALL;
        case CURSOR_SIZENESW:    return SDL_SYSTEM_CURSOR_SIZENESW;
        case CURSOR_SIZENS:      return SDL_SYSTEM_CURSOR_SIZENS;
        case CURSOR_SIZENWSE:    return SDL_SYSTEM_CURSOR_SIZENWSE;
        case CURSOR_SIZEWE:      return SDL_SYSTEM_CURSOR_SIZEWE;
        case CURSOR_WAIT:        return SDL_SYSTEM_CURSOR_WAIT;
        case CURSOR_DRAGGING:
        case CURSOR_POINTER:
        case CURSOR_NONE:
        case CURSOR_CUSTOM:
        default:
            return SDL_SYSTEM_CURSOR_ARROW;
    }
}

这里有几个值得注意的设计选择：

CURSOR_DRAGGING 映射到箭头：SDL 并没有专门的”拖动中”系统光标，因此回退到标准箭头是合理的。
CURSOR_CUSTOM 也映射到箭头：CURSOR_CUSTOM 的语义是”使用开发者通过 SetCursorImage 设置的自定义图片”。如果自定义图片未设置或未启用，回退到箭头光标能避免光标突然消失。
懒加载（Lazy Initialization）：系统光标只在第一次需要时通过 SDL_CreateSystemCursor 创建，并缓存到 mSysCursors 数组中。这避免了在应用启动时就为所有平台创建大量可能永远用不到的光标句柄。

从 MemoryImage 到 SDL_Cursor

相比系统光标，自定义光标的实现要复杂得多。PvZ-Portable 的图像系统使用 MemoryImage 作为内存位图的抽象，其像素数据以 BGRA32 格式存储在 mBits 指针中。而 SDL 创建自定义光标需要 SDL_Surface。因此，关键问题是如何在不复制像素数据的前提下，将 MemoryImage 包装为 SDL 表面。

笔者选择了 SDL_CreateRGBSurfaceWithFormatFrom，它允许直接从现有的像素缓冲区创建表面，而无需额外拷贝：

static SDL_Cursor* CreateCursorFromMemoryImage(MemoryImage* theImage)
{
    if (theImage == nullptr || theImage->mBits == nullptr)
        return nullptr;

    const int aWidth = theImage->GetWidth();
    const int aHeight = theImage->GetHeight();
    if (aWidth <= 0 || aHeight <= 0)
        return nullptr;

    SDL_Surface* aSurface = SDL_CreateRGBSurfaceWithFormatFrom(
        theImage->mBits,
        aWidth,
        aHeight,
        32,
        aWidth * static_cast<int>(sizeof(uint32_t)),
        SDL_PIXELFORMAT_BGRA32);
    if (aSurface == nullptr)
        return nullptr;

    SDL_Cursor* aCursor = SDL_CreateColorCursor(aSurface, 0, 0);
    SDL_FreeSurface(aSurface);
    return aCursor;
}

这段代码的技术细节包括：

零拷贝创建 Surface：SDL_CreateRGBSurfaceWithFormatFrom 直接使用 theImage->mBits 作为像素源，SDL_FreeSurface 时不会释放这个外部缓冲区，因此 MemoryImage 的生命周期不受影响。
像素格式对齐：MemoryImage 内部使用 32 位 BGRA，pitch 为 width * sizeof(uint32_t)，与 SDL_PIXELFORMAT_BGRA32 完全匹配。
热点坐标：SDL_CreateColorCursor 的 (0, 0) 热点对于 PvZ-Portable 的自定义光标资源来说是适用的。如果未来需要更精细的热点控制，可以在 MemoryImage 或 Image 接口中扩展元数据。

缓存策略与性能优化

自定义光标有一个显著的运行时开销：每次调用 SDL_CreateColorCursor 都会分配新的操作系统光标资源。如果在每一帧都重新创建，不仅会造成内存分配压力，还可能导致光标闪烁。因此，缓存机制必不可少。

笔者设计了一个双层缓存策略：

系统光标缓存

// SexyAppBase.h
SDL_Cursor* mSysCursors[NUM_CURSORS];

mSysCursors 是一个固定大小的指针数组。EnforceCursor() 在首次需要某个系统光标时调用 SDL_CreateSystemCursor，并将结果缓存到对应槽位。后续再切换到同一光标时直接命中，无需与操作系统交互。这些缓存在 SexyAppBase 析构时统一 SDL_FreeCursor 释放。

自定义光标缓存

// SexyAppBase.h
SDL_Cursor*  mCustomCursor;
Image*       mCustomCursorImage;
int          mCustomCursorImageNum;

自定义光标采用单例缓存模式（而非数组），原因如下：

资源开销更高：自定义光标的创建需要遍历像素数据、生成表面、再生成系统光标对象，成本远高于系统光标。
使用频率更低：游戏中大部分光标都是系统光标（箭头、手型、等待等），自定义光标只在特定场景出现，通常一次只会使用一张自定义图片。

缓存命中判定逻辑：

if (mCustomCursor != nullptr
    && mCustomCursorImage == aCursorImage
    && mCustomCursorImageNum == aCursorNum)
{
    aCursor = mCustomCursor;  // 命中缓存
}
else
{
    SDL_Cursor* aNewCursor = CreateCursorFromMemoryImage(aMemoryImage);
    if (aNewCursor != nullptr)
    {
        ResetCustomCursorCache();  // 释放旧缓存
        mCustomCursor = aNewCursor;
        mCustomCursorImage = aCursorImage;
        mCustomCursorImageNum = aCursorNum;
        aCursor = mCustomCursor;
    }
}

此外，如果上层逻辑通过 SetCursorImage() 替换了某光标编号对应的图片，且该编号正好是当前缓存的自定义光标，则必须立即失效缓存，否则新图片不会生效：

void SexyAppBase::SetCursorImage(int theCursorNum, Image* theImage)
{
    if ((theCursorNum >= 0) && (theCursorNum < NUM_CURSORS))
    {
        if (mCustomCursorImageNum == theCursorNum
            && mCursorImages[theCursorNum] != theImage)
            ResetCustomCursorCache();

        mCursorImages[theCursorNum] = theImage;
        EnforceCursor();
    }
}

EnableCustomCursors 同样会在关闭自定义光标时清空缓存，避免在禁用状态下仍持有不必要的系统资源。

隐藏光标与状态管理

除了”显示什么光标”之外，”是否显示光标”同样重要。原版引擎使用 CURSOR_NONE 和 CURSOR_CUSTOM 两个枚举值来表达”不显示系统光标”。在新的 SDL 实现中，笔者对 CURSOR_NONE 做了明确处理：

if (aCursorNum == CURSOR_NONE)
{
    SDL_ShowCursor(SDL_DISABLE);
    return;
}

当光标编号为 CURSOR_NONE 时，直接调用 SDL_ShowCursor(SDL_DISABLE) 隐藏鼠标指针，不再尝试创建或设置任何光标对象。这对于战斗场景、过场动画或全屏模式非常有用——玩家不希望一个巨大的箭头遮挡画面中心。

与此同时，从 CURSOR_NONE 切换回其他任何光标时，EnforceCursor() 的正常流程会在设置新光标后调用 SDL_ShowCursor(SDL_ENABLE)，确保指针重新出现。状态转换是可靠且可逆的。

结语

光标系统在游戏引擎中往往被视为”边缘功能”，但在跨平台移植的语境下，它其实是一个完整的子系统：从操作系统抽象、像素格式转换、资源生命周期管理到运行时缓存策略，每一个环节都需要仔细设计。

通过这次重构，PvZ-Portable 彻底摆脱了 Win32 光标的遗留包袱，获得了真正意义上的跨平台光标支持。无论是桌面平台（Windows、Linux、macOS）、移动平台（通过外接鼠标），还是 WebAssembly 浏览器环境，玩家都能获得一致且完整的光标交互体验。

⚠️ 版权与说明

重要：本项目仅包含代码引擎，不包含任何游戏素材！

PvZ-Portable 严格遵守版权协议。游戏的 IP（植物大战僵尸）属于 PopCap/EA。

要研究或使用此项目，你必须拥有正版游戏（如果没有，请在 Steam 或 EA 官网上购买）。你需要从正版游戏中提取以下文件放到 PvZ-Portable 的程序所在目录中。

main.pak
properties/ 目录

本项目的源代码以 LGPL-3.0-or-later 许可证开源，欢迎学习和贡献。

PvZ-Portable：长期运行稳定性修复——从计数器溢出到浮点精度悬崖

Mon, 13 Apr 2026 00:00:00 +0000

引言

在调试 PvZ-Portable 的过程中，笔者注意到一类只在长时间运行后才会显现的异常：当无尽模式推进到数十小时后，某些周期性动画开始出现肉眼可见的抖动——浓雾的波动不再平滑，水生植物的漂浮动画变得不连续，就连 UI 元素的闪烁节奏也会偶发错乱。

这些问题看似分布在不同子系统，其实根因只有一个：游戏计数器在不断累加后，首先会触碰到 IEEE 754 float 的精度问题；而 int32_t 的 signed overflow 则是另一个隐患。本文将记录笔者如何系统性地重构 PvZ-Portable 中的主计数器与动画相位计算，改进超长期运行的稳定性。

浮点精度

PvZ-Portable 的动画系统大量使用 float 来计算浓雾波动、弹坑水波、漂浮植物的正弦运动等周期性相位。这些计算的典型模式是：

float aTime = mMainCounter * 2.0f * PI / 200.0f;
float aWave = sin(aPos + aTime) * 2.0f;

mMainCounter 是每帧递增的整数计数器。问题在于，当这个大整数被转成 float 并乘以一个系数后，IEEE 754 单精度浮点有限的 24 位有效尾数 会让相位的增量逐渐丧失精度。

以漂浮植物为例，每帧增量约为 2π/200 ≈ 0.0314。当 mMainCounter 增长到约 1670 万 时，float 在该数量级下的相邻可表示值间距（ULP）会超过这个增量。这意味着相邻两帧的相位输入不再有区别，正弦函数的参数被卡住在更粗粒的近似值上，原本平滑的正弦波会退化为阶梯状抖动。按逻辑帧率 100 FPS 计算，这个临界点出现在运行约 46 小时 之后。

不同动画的缩放系数不同，触达的具体帧数略有差异，但都集中在 40～50 小时 这个区间。对于不停使用同一局存档的无尽模式玩家来说，这完全可能在正常游戏中触发。

精度衰减时间表

我们可以把漂浮植物当作典型案例，算一算它会如何随时间逐步坏掉。它的相位增量是 2π/200 ≈ 0.0314。float 的相邻可表示值间距（ULP）在不同数量级下如下：

运行时长	`mMainCounter`	`float` 的 ULP	等价效果
~46 小时	1.67×10⁷	0.0625	约 2 帧相位才更新一次，开始出现轻微顿挫
~93 小时	3.34×10⁷	0.125	约 4 帧一跳，肉眼可见的抽搐
~7.7 天	1.34×10⁸	1.0	约 32 帧（0.3 秒）一跳，已经完全不像平滑动画
~62 天	5.34×10⁸	4.0	约 128 帧（1.3 秒）一跳，像幻灯片
~248 天（`int32` 溢出前）	2.15×10⁹	8.0	约 255 帧（2.5 秒）才抽搐一下

也就是说，如果一个玩家真的把游戏挂到 int32_t 溢出前夕，荷叶每隔两秒半才会晃动一下。更糟糕的是，第 249 天溢出发生时，有符号 int 的 UB 会让相位瞬间跳变成一个完全不可预测的值——即使它此前勉强还能运行，此时也可能行为错乱。

`int32_t` 溢出的未定义行为

原版引擎使用 int32_t（即 int）存储 mMainCounter 和 mAppCounter。int32_t 的上限约为 21.47 亿，按 100 FPS 计算约 248 天 会触及溢出边界。在 C++ 中，有符号整数溢出是未定义行为，编译器可以据此做出任何假设，导致行为不可靠。

abs(INT_MIN) 在 C++ 中同样是 UB。旧代码里 mMainCounter / 8 % 22 - 11 的实际范围不可能触及 INT_MIN，但计数器类型一旦向无符号迁移，类似表达式的语义就会变得更危险：无符号减法下溢会得到一个巨大的正数，此时再套一层 abs() 就存在 UB 风险。

计数器类型重构

明确了这两个根因后，修复路径就很清晰了：先把所有计数器统一为 uint32_t，再在送入 float 之前对大周期取模。

将主计数器切换为 `uint32_t`

修复的第一步是将 mMainCounter（Board 类）和 mAppCounter（LawnApp 类）从 int32_t 改为 uint32_t。

旧代码：

// Board.h
int32_t mMainCounter;

// LawnApp.h
int mAppCounter;

修复后：

// Board.h
uint32_t mMainCounter;

// LawnApp.h
uint32_t mAppCounter;

无符号整数的溢出在 C++ 中是定义良好的模 2^32 回绕行为。这不仅彻底消除了 UB 风险，还顺带解决了一些工程上的麻烦：存档同步、跨平台联机、以及时间比较逻辑都因此获得了稳定的行为基线。数值周期性运行，配合前面提到的动画相位取模，回绕到 0 不会产生任何错误——计数器进入了任意时间尺度都定义正确的运行状态。

统一派生计数器

Board 中还存在着 mEffectCounter、mDrawCount、mIntervalDrawCountStart，以及 PoolEffect 中的 mPoolCounter。这些计数器同样参与周期性动画或时间间隔计算，必须保持一致的类型语义。笔者将它们全部统一为无符号类型：

// Board.h
uint32_t mEffectCounter;
uint32_t mDrawCount;
uint32_t mIntervalDrawCountStart;

// PoolEffect.h
unsigned int mPoolCounter;

存档同步路径的适配

PvZ-Portable 使用自定义的 Portable v4 存档格式。计数器类型变更后，序列化路径必须同步切换为无符号读写。

修改前：

c.SyncInt32(theBoard->mMainCounter);
c.SyncInt32(theBoard->mEffectCounter);

修改后：

c.SyncUInt32(theBoard->mMainCounter);
c.SyncUInt32(theBoard->mEffectCounter);

这确保了旧存档的兼容性不会被破坏（位模式不变，只是解释方式明确为无符号），同时消除了读档时可能的符号扩展歧义。

动画相位的周期性取模

计数器类型改对了，但这只消除了溢出层面的风险。但无论计数器怎么改，把它直接喂给 float 做周期运算，还是因精度问题而出现抖动。真正的办法是，在向 float 转换之前先对大周期取模，确保输入三角函数的数值始终处于安全精度范围内。

浓雾动画（Fog）

浓雾波动由两个周期参数共同决定（900 帧与 500 帧），其最小公倍数为 4500 帧。修复后的代码在转换前先对 4500 取模：

constexpr uint32_t FOG_ANIM_PERIOD = 4500;
float aTime = static_cast<float>(mMainCounter % FOG_ANIM_PERIOD) * PI * 2;

这保证无论游戏运行多久，aTime 的绝对值都不会超过 4500 × 2π ≈ 28274，在 float 的精度范围内游刃有余。

弹坑水波（Crater）

弹坑在泳池场景下的水波摆动周期为 200 帧：

constexpr uint32_t CRATER_ANIM_PERIOD = 200;
float aTime = static_cast<float>(mMainCounter % CRATER_ANIM_PERIOD)
              * (PI * 2.0f / static_cast<float>(CRATER_ANIM_PERIOD));

宝石迷阵旋转效果

宝石迷阵模式中的扭转动画每 1000 帧旋转一周：

constexpr uint32_t BEGHOULED_TWIST_ROTATION_PERIOD = 1000;
float aRotation = -static_cast<float>(mBoard->mMainCounter % BEGHOULED_TWIST_ROTATION_PERIOD)
                  * (2 * PI * 0.001f);

漂浮植物与咖啡豆

水生植物的漂浮效果，以及咖啡豆的上下波动，也都采用了类似的取模策略。

旧代码直接将整数计数器乘以系数 aCounter * 0.03f。修复后改用 fmod 在 double 精度下先对 2π 取模，再降级为 float：

float aTime = static_cast<float>(
    fmod((mRow * 97.0 + mPlantCol * 61.0 + static_cast<double>(aCounter)) * 0.03,
         2.0 * PI)
);

这里要特别小心，因为咖啡豆的相位计算不仅依赖计数器，还叠加了行和列的固定偏移，数值增长更快。

泳池波动（PoolEffect）

泳池的水面波纹由多组不同周期的正弦波叠加而成，涉及的周期包括 1600、300、1800、220、3200/3、200、720、640、88 帧等。笔者计算出这些周期的共同周期边界：316800 帧，作为主周期取模边界：

constexpr unsigned int POOL_PHASE_PERIOD = 316800u;
float aPoolPhase = (mPoolCounter % POOL_PHASE_PERIOD) * PI;

同时，PoolEffect 中负责计算焦散纹理的固定点代码里，原先使用 int 存储的位移量也被明确为 unsigned int，避免了左移运算在 signed 类型上的 UB 风险：

// 旧代码
int timeU = x << 17;
int timePool0 = mPoolCounter << 16;

// 修复后
unsigned int timeU = x << 17;
unsigned int timePool0 = mPoolCounter << 16;

闪烁颜色与 `abs` 的安全性

动画相位的问题解决了，计数器类型变更还牵出了一处接口层面的细枝末节。

GetFlashingColor 是游戏中广泛使用的闪烁/高亮颜色插值函数，原先接收 int theCounter。当参数改为 uint32_t 后，theCounter % theFlashTime 变为无符号取模，随后与有符号的中间值相减可能引发符号混乱。

修改前：

Color GetFlashingColor(int theCounter, int theFlashTime)
{
    int aTimeAge = theCounter % theFlashTime;
    // ... abs(aTimeInf - aTimeAge) ...
}

修改后：

Color GetFlashingColor(uint32_t theCounter, int theFlashTime)
{
    int aTimeAge = static_cast<int>(theCounter % static_cast<uint32_t>(theFlashTime));
    // ...
}

另一处风险在 Board::DrawUIBottom 中。旧代码：

int aWaveTime = abs(mMainCounter / 8 % 22 - 11);

迁移到 uint32_t 后，如果不做显式 static_cast<int>，mMainCounter / 8 % 22 - 11 会先进行无符号运算，结果小于 11 时会发生下溢，变成一个巨大的正数。修复后：

int aWaveTime = std::abs(static_cast<int>((mMainCounter / 8) % 22) - 11);

这样不但避免了无符号下溢，也彻底消除了 abs(INT_MIN) 的 UB 隐患。

数据一览

下表汇总了这次修复涉及的关键计数器及其长期运行特性：

计数器	旧类型	新类型	100 FPS 下的环绕/溢出周期
`mMainCounter`	`int32_t`	`uint32_t`	约 497 天（定义良好）
`mAppCounter`	`int`	`uint32_t`	约 497 天
`mPoolCounter`	`int`	`unsigned int`	约 497 天
`mEffectCounter`	`int32_t`	`uint32_t`	约 497 天
`mDrawCount`	`int32_t`	`uint32_t`	约 497 天

而浮点精度问题在取模修复前的表现为：

动画效果	缩放系数	出现可见抖动的预估时长（100 FPS）
漂浮植物	`2π/200`	约 46 小时
浓雾波动	`2π`	约 46～47 小时
咖啡豆浮动	`0.03`	约 48 小时
泳池波纹	`π`	约 46 小时

现在，所有计数器都改为无符号类型，即使无限递增也不会触发 UB；同时，所有动画的相位输入都被限制在一个安全的周期范围内，避免了长期运行的精度问题。

回绕对齐的缺陷

然而，uint32_t 的自然回绕周期 2^32 = 4294967296 与各动画的取模周期并不保证对齐。这意味着在约 497 天后的回绕瞬间，理论上会出现一次相位跳变。

举个例子，漂浮植物的周期是 200 帧。4294967296 % 200 = 96，所以回绕时 % 200 的结果会从 95 直接跳到 0，而不是正常地走完 96→199。这相当于半个周期的瞬时跳变——严格来说，水生植物上下浮动位置会在那一帧突然跳变。

同理，浓雾的 4500 帧周期也不整除 2^32（余数为 796），回绕时同样存在一次跳变。

要彻底消除这个跳变，理论上需要让计数器在所有动画周期的公倍数处回绕（比如 {4500, 200, 1000, 316800} 的最小公倍数是 792000 帧），或者让所有动画周期都整除 2^32——前者会破坏计数器用于非动画逻辑时的单调性，后者对含有因数 3、5 的周期（如 4500）根本不可能。

所幸，这个跳变只发生在连续运行 497 天后的一帧，且不会造成额外的任何破坏。与其引入复杂的全局同步机制，不如坦然接受这个理论上存在、实践中几乎不可见的瑕疵。

结语

这次修复的核心启示非常直观，却又极易被忽视：不要在热路径中将单调递增的大整数直接塞给 float 做周期性运算。对于以帧为单位计时的游戏引擎，24 位浮点尾数是一座真实存在的悬崖——运行约 46 小时后，它就会把平滑的动画变成一顿一顿的抖动。

与此同时，int32_t 的 signed overflow 在 C++ 中不是什么回绕到负数那么简单，它是实实在在的未定义行为。将计数器家族统一迁移到 uint32_t，不仅修复了 UB，还顺带获得了可预期的环绕语义和跨平台一致性。

PvZ-Portable 作为开源重实现，在处理这类长期运行假设时尤其需要谨慎。原版游戏很多设计可能并不精细，但现代平台上的开源重实现没有理由继承这种隐式的寿命限制。把计数器类型做对、把相位取模做对，才能确保玩家在任何时长下都能获得稳定体验。

⚠️ 版权与说明

重要：本项目仅包含代码引擎，不包含任何游戏素材！

PvZ-Portable 严格遵守版权协议。游戏的 IP（植物大战僵尸）属于 PopCap/EA。

main.pak
properties/ 目录

本项目的源代码以 LGPL-3.0-or-later 许可证开源，欢迎学习和贡献。

PvZ-Portable 资源释放时序安全：动画附件生命周期与 SDL 音频回调的硬防护

Fri, 10 Apr 2026 00:00:00 +0000

引言

在 PvZ-Portable 的开发和测试过程中，笔者遇到一类非常棘手的崩溃：它们不发生在游戏逻辑最繁忙的更新阶段，而是在某个对象被销毁、资源被释放的瞬间触发。这类崩溃的共同特征是——对象已经开始析构，但外部系统仍在通过指针或回调异步访问它。

本文将记录两个典型的修复：一是 Reanimator 动画附件系统的生命周期治理，解决特定僵尸动画在加载和卸载时的指针混乱与悬空引用；二是 SDL_mixer 音频实例的析构时序加固，防止音效回调在声音对象已释放后继续触碰悬垂内存。这两个子系统截然不同，但指向同一个底层问题：手动管理内存的 C++ 对象与外部 C 风格 API 之间的生命周期耦合。

Reanimator 动画附件的生命周期治理

崩溃现象与排查方向

最早触发问题的是投石车僵尸（Catapult Zombie）。在特定状态下切换贴图时，或者当包含该僵尸的关卡结束、动画资源被回收时，引擎会概率性崩溃。堆栈指向 Reanimator 的绘制路径或附件销毁路径，很容易让人误以为是图片资源本身的损坏或释放过早。

深入排查后，笔者发现问题的根源并不在资源加载器，而在 Reanimator 的 Atlas 语义与附件的释放约定 上。这两个层面的设计彼此交织，错误的假设一路传导，最终在高负载或对象销毁时被放大成崩溃。

Atlas 语义修正：区分编码句柄与真实指针

PvZ-Portable 的重实现支持 Reanim Atlas，这是一种将多张贴图合并到一张大图集上的优化机制。在 Atlas 模式下，动画帧数据中的 mImage 字段存储的并不是可以直接绘制的 Image* 指针，而是一个编码后的 Atlas 句柄。绘制时需要通过 GetEncodedReanimAtlas 解码，才能得到真正的贴图信息和子图坐标。

旧代码在 Reanimation::DrawTrack 中对这流程的处理存在逻辑漏洞：

// 旧代码（简化后）
Image* aImage = aTransform.mImage;
if (mDefinition->mReanimAtlas != nullptr && aImage != nullptr)
{
    ReanimAtlasImage* aAtlasImage = mDefinition->mReanimAtlas->GetEncodedReanimAtlas(aImage);
    if (aAtlasImage != nullptr)
        aImage = aAtlasImage->mOriginalImage;
    if (aTrackInstance->mImageOverride != nullptr)
        aAtlasImage = nullptr;
}

这段代码有两大问题：

第一，解码顺序错误。当某个 track 存在 mImageOverride（显示覆盖贴图）时，旧代码会先尝试将 aImage 当作 Atlas 句柄解码，然后再发现存在 override 并丢弃 Atlas 结果。这个顺序本身不致命，但它意味着 aImage 在没有 override 且不是合法 Atlas 句柄时，会被当作 raw Image* 使用——而实际上，如果 Atlas 存在，aImage 可能只是编码值，根本不是一个稳定可用的指针。

第二，对非 Atlas 图片的误判。旧代码的判定是：Atlas 存在且 aImage != nullptr，就进入 Atlas 解码分支。但逻辑上应该区分轨道变换自带的 frame image（可能是编码句柄）和显式指定的非 Atlas 覆盖图。如果开发者或游戏逻辑为某个 track 设置了一张普通的非 Atlas 图片作为 override，旧代码仍可能在 aImage 上执行 Atlas 解码，得到 nullptr 后又错误地把它当成空贴图处理。

修复后的逻辑彻底重写了分支结构：

// 修复后
Image* aImage = aTransform.mImage;
ReanimAtlasImage* aAtlasImage = nullptr;
if (mDefinition->mReanimAtlas != nullptr && aImage != nullptr)
{
    aAtlasImage = mDefinition->mReanimAtlas->GetEncodedReanimAtlas(aImage);
    if (aTrackInstance->mImageOverride != nullptr)
    {
        aImage = aTrackInstance->mImageOverride;
        aAtlasImage = nullptr;
    }
    else if (aAtlasImage == nullptr)
    {
        aImage = nullptr;  // 不合法的编码句柄，不能当作 raw Image* 使用
    }
}
else if (aTrackInstance->mImageOverride != nullptr)
{
    aImage = aTrackInstance->mImageOverride;
}

修改后的关键变化是：

ImageOverride 优先级最高。如果存在覆盖贴图，直接跳过 Atlas 路径，不再对 aImage 做任何假设性的解码。
严格区分 Atlas 编码句柄与 raw 指针。如果 Atlas 存在但解码失败，aImage 会被显式置为 nullptr，杜绝将非法编码值当作普通指针解引用的风险。
绘制时的矩阵计算也分层处理。如果 aAtlasImage 有效，使用 Atlas 的元数据计算 pivot；否则使用 aImage 自身的尺寸信息。

同一修复还同步应用于 GetCurrentTrackImage 和 GetTrackMatrix，确保查询和绘制两条路径的语义一致。

附件系统的释放

解决了 Atlas 语义问题后，另一类崩溃出现在 Attachment 系统的释放路径中。

在 PvZ-Portable 中，Attachment 是一种挂载在骨骼动画轨道上的特效容器。一个 Attachment 可以包含粒子系统（ParticleSystem）、拖尾（Trail）、子动画（Reanimation）甚至嵌套 Attachment。这些子资源的生命周期由 EffectSystem 统一管理，而 Attachment 本身则由 AttachmentHolder 通过一个 DataArray 分配和回收。

旧代码中存在两个互相加剧的问题：

问题一：Detach 后没有清理条目。

AttachmentDetachCrossFadeParticleType 用于在取消挂载某种粒子特效时，通知粒子系统进入 cross-fade 或死亡状态。旧代码的逻辑大概是：

for (int i = 0; i < aAttachment->mNumEffects; i++)
{
    if ( ... 找到匹配的粒子 ... )
    {
        if (theCrossFadeName)
            aParticleSystem->CrossFade(theCrossFadeName);
        else
            aParticleSystem->ParticleSystemDie();
    }
}

这段代码只通知了粒子系统死亡，却没有将对应的 AttachEffect 条目从 Attachment 的 mEffectArray 中移除。结果是：粒子系统消亡后，Attachment 仍然保留着一个指向已死粒子系统的 ID。当后续代码遍历该 Attachment 的效果数组时，会拿到一个无效 ID，进而解引用一个已释放或已标记为 mDead 的对象。

修复后的逻辑在通知粒子死亡的同时，立即将条目从数组中移除：

for (int i = 0; i < aAttachment->mNumEffects;)
{
    AttachEffect* aAttachEffect = &aAttachment->mEffectArray[i];
    // ... 匹配粒子逻辑 ...
    if (匹配成功)
    {
        if (theCrossFadeName)
            aParticleSystem->CrossFade(theCrossFadeName);
        else
            aParticleSystem->ParticleSystemDie();

        // 立即从数组中移除该条目
        int aNumEffectsRemaining = aAttachment->mNumEffects - i - 1;
        if (aNumEffectsRemaining > 0)
            memmove(aAttachEffect, aAttachEffect + 1, aNumEffectsRemaining * sizeof(AttachEffect));
        aAttachment->mNumEffects--;
        continue;
    }
    i++;
}

if (aAttachment->mNumEffects == 0)
{
    aAttachment->mDead = true;
    theAttachmentID = AttachmentID::ATTACHMENTID_NULL;
}

这样，Attachment 的所有权状态与底层粒子系统的实际生命周期始终保持一致。当最后一个 effect 被移除时，Attachment 自身也会立即被标记为死亡，不再被误用。

问题二：没有主动回收死附件。

AttachmentHolder::AllocAttachment 负责从 DataArray 中分配新的 Attachment。旧代码直接调用 DataArrayAlloc，没有任何容量满时的回收机制。如果 DataArray 接近容量上限，分配会失败，或者更糟糕的是——分配器可能复用一个尚未正确清理的槽位，导致新对象带着旧附件的残留数据。

修复方案是在 AllocAttachment 中引入预分配时的垃圾回收：当数组快要满时，先遍历所有现有 Attachment，调用新增的 PruneDeadEffects 函数清理已死亡的 effects，然后释放掉所有已经完全死亡的 Attachment。

Attachment* AttachmentHolder::AllocAttachment()
{
    if (mAttachments.mSize + 1 >= mAttachments.mMaxSize)
    {
        // ... 遍历所有 attachment，执行 PruneDeadEffects ...
        // ... 将 mDead 的 attachment ID 收集到数组 ...
        // ... 逐个调用 DataArrayFree 释放死附件 ...
    }
    return mAttachments.DataArrayAlloc();
}

PruneDeadEffects 是一个集中式的状态清理器。它会检查 Attachment 上的每一个 effect，若对应的底层对象（粒子、Trail、Reanim、子 Attachment）已经死亡或无效，就通过 memmove 将其从紧凑数组中移除。这个函数既在分配压力的垃圾回收时被调用，也可以在未来需要时作为维护接口使用。

投石车僵尸的调用侧修正

在 Atlas 语义修正的同时，笔者还修复了 Zombie::UpdateReanim 中投石车僵尸对 GetCurrentTrackImage 的调用：

// 旧代码
Image* aPoleImage = aReanim->GetCurrentTrackImage("Zombie_catapult_pole");
if (aPoleImage == IMAGE_REANIM_ZOMBIE_CATAPULT_POLE_WITHBALL && mSummonCounter != 0)
{
    aReanim->SetImageOverride(...);
}

这段代码试图通过查询当前轨道的贴图来判断投石车是否还载着篮球。但 GetCurrentTrackImage 在 Atlas 模式下返回的是不稳定的气候编码句柄，用它和特定的常量 Image* 做等值比较本身就是不可靠的。正确的逻辑应当直接依赖 mSummonCounter 这个已被计算好的状态变量：

// 修复后
if (mSummonCounter != 0)
{
    aReanim->SetImageOverride("Zombie_catapult_pole", IMAGE_REANIM_ZOMBIE_CATAPULT_POLE_DAMAGE_WITHBALL);
}

不仅消除了 Atlas 句柄与 raw 指针比较带来的未定义行为，也让状态转换意图更加清晰。

这里插入一个关于 ResourceManager 的附带修复。在审查资源加载代码时，笔者为 ParseImageResource 中 sprite sheet 的 rows 和 cols 属性增加了 TOD_ASSERT 正向边界检查。这是一个防御性措施：如果资源配置文件因为格式错误或版本不一致而写入非正数，引擎可以在加载阶段就断言失败，而不是将零或负数带入后续的纹理切分计算中导致更隐蔽的崩溃。

SDL 音频回调与对象析构的时序博弈

另一类崩溃出现在音效密集播放的场景：当僵尸数量很多、豌豆射手和西瓜投手同时开火时，游戏概率性 segfault，堆栈往往指向 SDL_mixer 的某个 effect callback 内部。

这个问题与动画附件系统的崩溃在表面上毫无关联，但究其本质，仍然是对象已经释放，外部回调还在继续访问它。

通道所有权的缺失

PvZ-Portable 使用 SDL_mixer 作为音频后端。音效播放的流程大致是：

SDLSoundManager 维护一个 Mix_Chunk 数组（mSourceSounds）和一个固定大小的通道池（mPlayingSounds）。
当需要播放某个音效时，SDLSoundManager 找到一个空闲通道，创建一个 SDLSoundInstance 对象，然后调用 Mix_PlayChannel 开始播放。
为了支持音高变化（pitch），代码在 Mix_PlayChannel 之后通过 Mix_RegisterEffect 注册了一个回调函数 PitchHandlerFuncCallback，该回调会在 SDL_mixer 的混音线程中定期被调用。

旧代码中的 SDLSoundInstance 构造如下：

SDLSoundInstance::SDLSoundInstance(SDLSoundManager* theSoundManager, Mix_Chunk* theSourceSound)
{
    // ...
    mChannel = -1;
}

播放时调用 Mix_PlayChannel(-1, ...) 让 SDL_mixer 自动分配通道。mChannel 只是被动记录 SDL_mixer 返回的通道号。这里的关键问题是：SDLSoundInstance 并不知道自己被绑定到了哪个通道。虽然 SDLSoundManager 在 mPlayingSounds 数组中以通道号为索引存放了实例指针，但实例对象本身并没有保留这个绑定关系。

析构时序的竞争

更致命的是，SDLSoundInstance 的析构函数在旧代码中是完全空的：

SDLSoundInstance::~SDLSoundInstance()
{
    // 什么都不做
}

这意味着，如果某个音效实例因为以下原因被销毁：

自动释放逻辑（mAutoRelease）在播放结束后触发；
上层逻辑主动调用 Release()；
SDLSoundManager 在清理时覆盖该通道；

那么 SDL_mixer 的混音线程仍可能在下一个 audio callback 中调用 PitchHandlerFuncCallback(mChannel, ...)，而这个回调需要读取 SDLSoundInstance 的成员 mPitchHandler。一旦实例已被 delete，这就是典型的 use-after-free。

修复：斩断回调先于停止播放

修复的核心时序非常明确：在对象死亡之前，必须先切断外部系统对它的访问路径。具体到 SDL_mixer，就是先 Mix_UnregisterAllEffects 注销 effect 回调，再 Mix_HaltChannel 停止播放。

修改后的 Stop() 实现：

void SDLSoundInstance::Stop()
{
    if (mChannel >= 0 && mChannel < MAX_CHANNELS)
    {
        Mix_UnregisterAllEffects(mChannel);
        Mix_HaltChannel(mChannel);
        mChannel = -1;
    }
    mAutoRelease = false;
}

析构函数现在改为：

SDLSoundInstance::~SDLSoundInstance()
{
    Stop();
}

这样，当 SDLSoundInstance 被销毁时，它会主动停止自己绑定的通道，并且在停止之前彻底注销 pitch effect。即使 Mix_HaltChannel 的执行存在异步延迟，由于回调已经被取消，混音线程不会再触碰这个垂死对象的任何成员。

通道保留与稳健边界

除了时序修复，笔者还为 SDLSoundInstance 增加了通道保留机制。SDLSoundManager 的空闲通道查找和实例创建逻辑天然确保了每个实例都有一个确定的通道，但旧代码没有把这个信息传递给实例。修复后：

// 构造时传入预留的通道号
SDLSoundInstance::SDLSoundInstance(SDLSoundManager* theSoundManager,
                                   Mix_Chunk* theSourceSound,
                                   int theReservedChannel);

// SDLSoundManager 中
mPlayingSounds[aFreeChannel] = new SDLSoundInstance(
    this, mSourceSounds[theSfxID], aFreeChannel);

播放时优先请求该保留通道：

const int aTargetChannel =
    (mReservedChannel >= 0 && mReservedChannel < MAX_CHANNELS) ? mReservedChannel : -1;
mChannel = Mix_PlayChannel(aTargetChannel, mMixChunk, (looping) ? -1 : 0);

如果 Mix_PlayChannel 返回 -1（例如该通道被其他高优先级声音抢占），mChannel 会被显式设为 -1，避免残留旧值导致后续操作越界。

同时，所有涉及 mChannel 的边界判断都收紧为 mChannel >= 0 && mChannel < MAX_CHANNELS，杜绝负数索引或越界数组访问的风险。

结语

动画附件系统的崩溃和 SDL 音频回调的崩溃，表面上分属两个毫不相干的子系统，但它们共享同一个底层模式：手动管理内存的 C++ 对象在析构阶段，外部 C 风格的异步系统仍在通过指针或回调访问它。

对 Reanimator 的修复思路是建立显式的所有权清理和垃圾回收：确保 Attachment 的 effect 数组与底层粒子/动画/Trail 的实际生命周期同步，并在分配压力下主动回收死对象。对 SDL 音频的修复思路则是在对象死亡之前，按正确顺序切断外部回调：先 UnregisterEffects，再 HaltChannel，析构函数绝不空手而归。

这两种思路——清理引用链和切断访问路径——是处理 C++ 与底层 C API 混用时生命周期问题的基本工具。PvZ-Portable 作为对 legacy 引擎的重实现，在处理这类历史遗留假设时仍需持续投入精力。

⚠️ 版权与说明

重要：本项目仅包含代码引擎，不包含任何游戏素材！

PvZ-Portable 严格遵守版权协议。游戏的 IP（植物大战僵尸）属于 PopCap/EA。

main.pak
properties/ 目录

本项目的源代码以 LGPL-3.0-or-later 许可证开源，欢迎学习和贡献。

PvZ-Portable：渲染层缓冲区的安全重构与边界保护

Thu, 09 Apr 2026 00:00:00 +0000

引言

此前，笔者集中修复了渲染子系统中一类隐藏很深的底层缺陷：OpenGL 顶点缓冲中的越界风险、不匹配的内存释放，以及缺失的边界防护。这些问题与游戏逻辑无关，却在复杂特效或高负载场景下有直接触发崩溃的风险。

本文将详细记录这次对 PvZ-Portable 渲染层的安全重构过程，包括裸数组的 RAII 化、顶点追加时序的修正、粒子特效裁剪阶段的溢出保护，以及一个长期潜伏的 delete/delete[] 不匹配问题。

旧顶点缓冲区的隐患

PvZ-Portable 的 OpenGL 渲染后端采用批量提交（batching）策略：将尽可能多的几何体合并到同一个 draw call 中，再统一调用 glDrawArrays。为了暂存这些顶点数据，引擎维护了一个全局的静态缓冲区 gVertices。在重构之前，它的实现非常直接——一块通过 new[] 分配的固定大小裸数组：

static GLVertex* gVertices;

// 初始化
gVertices = new GLVertex[MAX_VERTICES]();

所有向 GPU 提交顶点的操作都围绕这个数组进行。GfxAddVertices 负责将新的顶点 memcpy 到 gVertices + gNumVertices 的位置，然后累加计数器。旧代码的逻辑看起来大致是这样：

static void GfxAddVertices(const GLVertex *arr, int arrCount)
{
    if (gVertexMode == (GLenum)-1) return;

    memcpy(gVertices + gNumVertices, arr, sizeof(GLVertex) * arrCount);
    gNumVertices += arrCount;

    if (gNumVertices >= MAX_VERTICES)
    {
        GLenum oldMode = gVertexMode;
        GfxEnd();      // 提交当前批次
        GfxBegin(oldMode); // 开始新批次
    }
}

这段代码的问题在于边界检查的时序。memcpy 发生在容量判定之前，这意味着如果某一次调用传入的顶点数量直接超过了数组剩余容量，数据会在边界检查触发 flush 之前就写到了数组末尾之外。这是明确的未定义行为，可能导致直接崩溃。

此外，gVertices 作为全局裸指针，其生命周期完全依赖 GLInterface 的构造函数和析构函数手动管理。new[] 与 delete[] 虽然配对正确，但整个设计没有任何自动边界保护或异常安全保证。

向 `std::vector` 重构与追加前 flush

修复的第一步是彻底改造顶点缓冲的内存模型。笔者将 gVertices 从裸指针替换为 std::vector<GLVertex>，利用 C++ 标准容器的自动扩容和 RAII 语义来消除手动分配风险：

static std::vector<GLVertex> gVertices;

如果只是简单地把 memcpy 改成 push_back，时序问题依然存在。真正的关键是把边界检查从追加后移到追加前。为此，笔者引入了一个独立的辅助函数 GfxFlushIfOverBudget()：

static void GfxFlushIfOverBudget()
{
    if (gVertexMode == (GLenum)-1 || gNumVertices < MAX_VERTICES)
        return;

    GLenum oldMode = gVertexMode;
    GfxEnd();
    GfxBegin(oldMode);
}

这个函数在每次追加操作完成后被调用，用于判断当前累积的顶点数是否已经达到了单批次提交的上限。如果 gNumVertices 已经触及 MAX_VERTICES，它会立即强制提交当前批次，清空缓冲区，然后开始新的批次。结合 std::vector 的使用，新的 GfxAddVertices 变成了下面这样：

static void GfxAddVertices(const GLVertex *arr, int arrCount)
{
    if (gVertexMode == (GLenum)-1) return;
    if (arrCount <= 0) return;

    const int oldCount = gNumVertices;
    gNumVertices += arrCount;
    gVertices.resize(gNumVertices);
    memcpy(gVertices.data() + oldCount, arr, sizeof(GLVertex) * arrCount);

    GfxFlushIfOverBudget();
}

resize(gNumVertices) 会在 std::vector 需要扩容时自动重新分配内存，并安全地迁移已有数据，这意味着 memcpy 的目标地址 gVertices.data() + oldCount 始终是合法的——无论 gNumVertices 增长到多大，都不会再出现裸数组时代的写越界。

随之而来的是 MAX_VERTICES 的语义转变：在裸数组时代，它是防止缓冲区溢出的硬边界；而在使用 std::vector 之后，它变成了单批次向 GPU 提交顶点的上限。GfxFlushIfOverBudget 保障的是渲染性能与驱动兼容性，而不是防止内存损坏。也就是说，即使某次追加后 gNumVertices 暂时超过了 MAX_VERTICES，数据本身仍然是安全地存放在已扩容的 std::vector 中的，唯一的后果是 GfxEnd() 被触发时，这次向 GPU 提交的 draw call 可能会略微大于 MAX_VERTICES 的设定值。

GfxEnd() 本身也得到了加固：

static void GfxEnd()
{
    if (gVertexMode == (GLenum)-1) return;

    if (gNumVertices > 0)
    {
        glBindBuffer(GL_ARRAY_BUFFER, gVbo);
        glBufferData(GL_ARRAY_BUFFER, sizeof(GLVertex) * gNumVertices,
                     gVertices.data(), GL_DYNAMIC_DRAW);

        // 设置 vertex attributes ...
        glDrawArrays(gVertexMode, 0, gNumVertices);
    }

    gVertexMode = (GLenum)-1;
    gNumVertices = 0;
    gVertices.clear();
}

绘制命令现在只在 gNumVertices > 0 时才执行，避免了对空缓冲区发起无意义的 glDrawArrays。批次结束后 gVertices.clear() 会保留已分配的容量（因为 clear() 不释放内存），这样下一帧的追加通常不需要重新进行堆分配。

在 GLInterface 的析构函数中，旧代码需要显式 delete[] gVertices，现在这一步也被 std::vector 的自动析构所取代，彻底消除了手动内存管理中的泄漏风险。

裁剪阶段的溢出保护

顶点缓冲区的主路径安全了，但还有一个侧路径同样危险——EffectSystem 中的三角形裁剪与追加逻辑。

TodTriangleGroup::AddTriangle 负责接收一个三角形，根据当前的裁剪矩形将其切分为多个子三角形，然后把结果写入 mVertArray 数组。这个数组的大小由 MAX_TRIANGLES 定义。旧代码在循环内直接写入：

int vCount = Tod_clipShape(clipped, aTriRef[i], clipX0, clipX1, clipY0, clipY1);
for (int j = 0; j < vCount - 2; j++)
{
    TriVertex* pVert = mVertArray[mTriangleCount];
    pVert[0].x = clipped[0]->x;
    // ... 填充顶点数据 ...
    mTriangleCount++;
}

问题在于，当一个复杂的粒子特效触发裁剪时，单个输入三角形可能被切分成数十个子三角形。如果此时 mTriangleCount 已经接近 MAX_TRIANGLES，循环内没有任何容量检查，最终一定会写穿 mVertArray 的边界。

这一问题只有在 mVertArray 接近其容量上限时才会显现，因此之前长期未被发现。修复非常直接：在每次增量前检查容量，若已满则先 DrawGroup(g) 提交当前积攒的三角形：

for (int j = 0; j < vCount - 2; j++)
{
    if (mTriangleCount == MAX_TRIANGLES)
        DrawGroup(g);

    TriVertex* pVert = mVertArray[mTriangleCount];
    // ... 填充顶点数据 ...
    mTriangleCount++;
}

由于这种极端裁剪场景触发概率不高，再加上不同平台内存分配器对越界写入的容忍度不同，这个缺陷在此前并未引起足够注意。但在更严格的运行环境（如特定的 GPU 驱动）下，以及某些无尽模式情形的高压力下，能稳定复现崩溃。

隐藏已久的 `delete`/`delete[]` 不匹配

在审查顶点缓冲相关代码时，笔者还注意到了一个与 OpenGL 无关但同样危险的内存管理错误，它藏在 VertexList 结构体中。

VertexList 是一个小型的动态数组实现，用于临时存放一组 GLVertex。它的内部分配逻辑是这样的：

void reserve(int theCapacity)
{
    if (theCapacity > mCapacity)
    {
        GLVertex* aNewList = new GLVertex[theCapacity];
        memcpy(aNewList, mVerts, mSize * sizeof(mVerts[0]));
        if (mVerts != mStackVerts)
            delete mVerts;

        mVerts = aNewList;
    }
}

以及析构函数：

~VertexList()
{
    if (mVerts != mStackVerts)
        delete mVerts;
}

这里的问题非常经典：使用了 new[] 分配数组，却用 delete（标量删除）来释放。根据 C++ 标准，这是未定义行为。虽然标准的 delete 和 delete[] 在简单类型如 GLVertex 上可能不会立刻崩溃，但它们在底层可能调用不同的释放逻辑：

new[] 通常会在返回的指针前面额外存储数组元素个数；
delete 不会读取这个前缀，只会释放单个对象大小的内存；
这会导致分配的内存和释放的内存大小不一致，逐渐腐蚀堆的元数据。

在短生命周期对象上，这个错误可能数年都不被察觉。但当引擎运行时间变长、对象分配变得非常频繁时，堆元数据的损坏会在完全无关的代码位置引发难以解释的崩溃。修复只需要把两处 delete mVerts; 改成 delete[] mVerts;。未定义行为不会因为当前平台暂未崩溃而变得安全。不同的内存分配器实现对这种不匹配的敏感程度各不相同，在一种环境下稳定的程序，换到另一种环境下就可能出现难以追踪的崩溃。

结语

这次对渲染层缓冲区安全的集中修复，本质上是对底层代码中遗漏边界和生命周期管理的系统补齐。这些缺陷在过去可能因为触发概率低、触发场景少而没有立刻暴露，但它们始终是潜在的风险点。

PvZ-Portable 的跨平台工作还在持续，这类底层基础设施的健壮化也将是后续的重点方向。

⚠️ 版权与说明

重要：本项目仅包含代码引擎，不包含任何游戏素材！

PvZ-Portable 严格遵守版权协议。游戏的 IP（植物大战僵尸）属于 PopCap/EA。

main.pak
properties/ 目录

本项目的源代码以 LGPL-3.0-or-later 许可证开源，欢迎学习和贡献。

Qt Web Extractor 新增 MCP 支持：为 AI 编程助手提供高级网页提取

Sat, 04 Apr 2026 00:00:00 +0000

背景

之前笔者写过一篇介绍 Qt Web Extractor 的文章，讲了这个项目是怎么用系统 Qt WebEngine 来做轻量级网页内容提取的。项目一直提供了 HTTP REST API 和 Open WebUI 的集成方式，给 AI 平台调用本来就不是问题——在 Open WebUI 里配置一下外部网页加载器，或者直接用 tool.py 作为自定义工具，都能很方便地让 LLM 获取网页内容，几乎是一键式集成。

不过对于 Claude Code、OpenCode 这类 AI 编程助手，Qt Web Extractor 此前事实上还不能开箱即用，需要手动配置。这些工具本身支持 MCP 协议来扩展能力，如果网页提取服务也能以 MCP 的方式暴露出来，那在终端对话中需要查阅在线文档、阅读 API 参考的时候，AI 助手就能直接调用，不需要任何额外的脚本或配置。

与简单的 HTTP 抓取服务不同，本工具有能力处理目前占据主流的复杂动态渲染页面，不仅能提取出其他基础工具获取不到的动态内容，基于完整渲染页面转换得到的 Markdown 还保留了超链接、表格结构、代码块等丰富结构信息。这意味着模型在阅读内容后，可以顺着超链接继续获取相关的参考文档，形成信息获取的良性循环。

所以这次更新，项目在原有的 HTTP 服务基础上内建了 MCP（Model Context Protocol）支持。这算是锦上添花——几乎没有引入任何额外的代码负担和运行开销，只是 server.py 里多处理了一个 /mcp 端点，但大大方便了终端 AI 工具的使用体验。Claude Code、OpenCode 这类工具在对话中遇到需要读取网页内容的场景时，会调用这个 MCP 工具，整个过程非常顺畅。

什么是 MCP

MCP 是 Anthropic 提出的一种开放协议，用来标准化 AI 模型与外部工具之间的交互方式。服务端按照协议暴露一组工具（tools），客户端通过标准的 JSON-RPC 调用来请求执行，服务端返回结构化的结果。

对于 Qt Web Extractor 来说，MCP 的价值不在于让 AI 能调用——这一点原来的 REST API 和 Open WebUI 集成已经做得很好了——而在于让 Claude Code、OpenCode 这类终端 AI 工具能原生地发现和使用这个能力。AI 助手启动时会读取可用的 MCP 工具列表，在对话中遇到需要读取网页的场景时，会自动选择调用，整个过程不需要用户手动干预。

另外，笔者在工具描述中特别写了 Always prioritize this tool when you need to read, fetch, or analyze content from any URL or web link，这样 AI 模型在多个可用工具中会优先选择本工具来处理网页内容，避免使用自带的简单 HTTP 请求工具导致无法获取动态渲染内容或者格式不佳的情况。

实现方式

Qt Web Extractor 的 MCP 支持是直接内建在已有的 HTTP 服务里的，不需要额外启动任何进程。服务启动后，除了原有的 REST API 端点，还会在 /mcp 路径上响应 MCP 协议的 JSON-RPC 请求。

协议处理

MCP 基于 JSON-RPC 2.0，服务端需要处理几个标准方法：

initialize：客户端初始化握手，返回协议版本和服务端信息
ping：心跳检测
tools/list：返回可用的工具列表
tools/call：执行具体的工具调用

这些都在 server.py 的 _Handler 类中实现。以 tools/list 为例，它会返回一个 fetch_url 工具的定义：

{
    "name": "fetch_url",
    "description": (
        "Advanced web content extractor. Fully evaluates JavaScript "
        "to render modern web pages and converts the result into clean "
        "Markdown. Always prioritize this tool when you need to read, "
        "fetch, or analyze content from any URL or web link."
    ),
    "inputSchema": {
        "type": "object",
        "properties": {
            "url": {
                "type": "string",
                "description": "The URL to extract content from.",
            }
        },
        "required": ["url"],
        "additionalProperties": False,
    },
    "_meta": {
        "anthropic/maxResultSizeChars": 500000,
    },
}

工具描述里明确告诉 AI 模型这是一个高级网页提取器，能完整执行 JavaScript 并返回干净的 Markdown 格式内容。_meta 中的 anthropic/maxResultSizeChars 是 Anthropic 的扩展字段，用来告知客户端单次返回的最大字符数。

提取流程

当 AI 助手调用 fetch_url 工具时，服务端会走和 REST API 相同的提取管线：

解析请求参数，获取目标 URL
自动检测是否为 PDF 链接（先检查 .pdf 后缀作为快速路径，否则发送 HEAD 请求检查 Content-Type）
将提取请求放入队列，由 Qt 主线程的 WebEngine 执行渲染
等待页面加载完成，提取 Markdown 文本
返回结构化结果，包含 URL、标题、Markdown 内容和可能的错误信息

返回格式遵循 MCP 的工具调用规范：

{
    "content": [{"type": "text", "text": "页面 Markdown 内容..."}],
    "structuredContent": {
        "url": "https://example.com",
        "title": "Example Domain",
        "markdown": "页面 Markdown 内容...",
        "error": ""
    },
    "isError": false
}

content 字段是 AI 模型直接阅读的文本，structuredContent 则保留了完整的结构化数据，方便客户端做进一步处理。

架构设计

Qt WebEngine 的页面加载必须在 Qt 主线程的事件循环中运行，而 HTTP 服务是在后台线程处理的。两者之间的通信通过一个线程安全的队列来实现：

class _ExtractRequest:
    __slots__ = ("url", "pdf", "result", "done")

    def __init__(self, url: str, pdf: bool = False):
        self.url = url
        self.pdf = pdf
        self.result: _ExtractionResult | None = None
        self.done = threading.Event()

HTTP 处理线程创建一个 _ExtractRequest 放入队列，Qt 主线程从队列中取出请求、执行提取、设置结果并触发 done 事件。HTTP 线程等待 done 信号后读取结果返回给客户端。这个设计和原有的 REST API 共享同一套机制，MCP 只是多了一个协议解析层。

使用方式

启动服务

首先启动 Qt Web Extractor 的 HTTP 服务：

qt-web-extractor serve --host 127.0.0.1 --port 8766

如果需要 API Key 认证：

qt-web-extractor serve --host 127.0.0.1 --port 8766 --api-key mysecretkey

Claude Code

Claude Code 提供了命令行方式来添加 MCP 服务端：

# 无认证
claude mcp add --transport http web-extractor http://127.0.0.1:8766/mcp

# 如果服务端设置了 --api-key
claude mcp add --transport http web-extractor http://127.0.0.1:8766/mcp \
  --header "Authorization: Bearer mysecretkey"

也可以通过配置文件来管理。项目根目录的 .mcp.json 作用于当前项目，~/.claude.json 中的 mcpServers 则是全局配置：

{
  "mcpServers": {
    "web-extractor": {
      "type": "http",
      "url": "http://127.0.0.1:8766/mcp",
      "headers": {
        "Authorization": "Bearer mysecretkey"
      }
    }
  }
}

OpenCode

OpenCode 的配置写在 opencode.json（项目根目录）或 ~/.config/opencode/opencode.json（全局）中：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "web_extractor": {
      "type": "remote",
      "url": "http://127.0.0.1:8766/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer mysecretkey"
      }
    }
  }
}

关于认证

MCP 端点和 REST API 共用同一个认证机制。手动启动服务时通过 --api-key 设置密钥，而使用 systemd 服务时则是在 /etc/qt-web-extractor.conf 中取消 API_KEY= 的注释并填入密钥。无论哪种方式，客户端在请求头中带上 Authorization: Bearer <key> 即可通过验证。如果不设置 API Key，所有端点都无需认证即可访问。

实际使用场景

配置好以后，用起来就很自然了。比如在 OpenCode 里问一句：

> 帮我看看 https://github.com/wszqkzqk/qt-web-extractor 是怎么设计的

模型会自动调用 fetch_url 工具把页面内容拉下来，然后基于渲染后的完整页面转化得到的干净整洁的 Markdown 来回答。对于查阅在线文档、对比 API 设计、看某个项目的使用说明这些场景，这个流程都颇为顺畅。

与原有功能的配合

MCP 支持只是多了一个接口，不影响原有的任何使用方式。项目目前提供了四种使用方式：

命令行工具：快速提取，适合脚本和一次性使用
Python API：作为库集成到自己的项目中
HTTP REST API：为 Open WebUI 等平台提供网页加载服务
MCP 协议：为 Claude Code、OpenCode 等终端 AI 工具提供原生调用

它们共享同一个提取引擎，底层都是 Qt WebEngine 在执行渲染。后台服务可以同时响应 REST API 和 MCP 请求，互不干扰。

总结

这次 MCP 支持的加入，对于日常使用 Claude Code、OpenCode 等终端 AI 助手的开发者来说，查阅在线文档、分析网页内容已经变得和读写本地文件一样自然。

项目依然保持了轻量、简洁的特点——没有引入任何额外的依赖，MCP 协议处理只是 server.py 中新增的几百行代码，几乎不存在额外开销。服务启动后，REST API 和 MCP 端点同时可用，按需取用。

项目仓库地址：GitHub · Qt Web Extractor

项目协议：GPL-3.0-or-later

Arch Linux for Loong64 构建与调试的 AI 辅助 SKILL 编写记

Sat, 04 Apr 2026 00:00:00 +0000

前言

近年我们在为 Arch Linux 适配 LoongArch 架构（loong64）的过程中，遇到了大量软件包构建、移植和调试的挑战。Arch Linux 的官方打包体系底层依赖 devtools 和 archbuild 系列工具箱。虽然这套构建工具非常强大，利用 systemd-nspawn 容器和 Btrfs 快照实现了极高的环境隔离性，让宿主机保持干净整洁，但它的复杂性也带来了潜在的门槛。

随着 AI 辅助编程工具日益普及，笔者在日常的打包维护工作中，越来越多地尝试让大模型参与解决某些构建失败排查、修复补丁并处理依赖升档的任务。然而，通用性很强的大模型一旦脱离了传统应用层代码，进入到 Arch Linux 那错综复杂的隔离构建黑盒中，常常会暴露出极大的幻觉：

常常试图在宿主机的 Git 仓库里直接调用 make 而非在 chroot 内部操作。
搞不清楚挂载目录的权限（例如盲目尝试去修改被只读挂载的 /startdir/PKGBUILD）。
完全没有“保护干净模板”的潜意识，甚至有时会直接污染存放 root 模版的只读系统目录。
在需要连续构建多个相互依赖的包（例如 soname bump 的连锁重构）时，根本不知道要如何搭建并复用本地的 pacman 软件源。

为此，笔者专门编写了一套针对 archlinux-loong64-portbuild 工作流的专属 SKILL 文件。本文主要讨论这份 SKILL 的技术设计思路、覆盖的使用场景，并探讨如何通过提供高质量的上下文指导系统，把通用大语言模型真正调优成一位“Arch Linux 官方打包团队专家”。

核心痛点与系统设计理念

由于模型本身并不是一个真实的 Linux 用户，我们要赋予它解决问题的能力，就必须先把 Archbuild 底层的运转流程灌输给它。在整个 SKILL 文件中，笔者着重强调了以下几条核心的设计理念。

环境隔离

这是阻挡模型瞎乱操作的第一道防线。笔者在设定上，将“宿主机”、“Btrfs 快照工作区”以及“干净的 Chroot 模板”做了非常清晰的职能划分。模型被要求严格遵守“宿主机禁止直接编译”和“绝不污染模板环境”两条铁律。

为了彻底解决 AI 读错文件目录的问题，SKILL 中抽象定义了一张路径映射表（Path Mapping）。一旦构建失败，模型需要查阅日志并自动将宿主机的仓库路径转换到容器内的工作路径进行思考。例如，向模型讲清楚 sed 的目标应该位于 /build/<pkgbase>/src/，而不是宿主机所在的 /startdir/。这不仅避免了误操作，也使 AI 分配的调试命令不再充满错误路径。

规范调试与固化工作流

没有约束的 AI 会像盲头苍蝇。面对编译报错（如段错误或链接错误），模型最喜欢做的事情就是随意修改 PKGBUILD 然后建议用户重头再跑一遍 extra-loong64-build，导致每次都要重新下载数十兆的源码跑好几分钟——这极大浪费了生命和算力。

因此，笔者在 SKILL 中要求其遵循一种符合人类专家习惯的标准工作流：

保存现场：建议用户使用 btrfs subvolume snapshot 将出错容器备份。
切入环境：利用 systemd-nspawn -aD 配合正确的用户身份进入已有容器。
定位分析：进入真正的 /build/ 目录进行快速迭代（只需局部使用 makepkg --check 等轻量化指令即可快速验证，避免全量重建）。

把补丁冲突降至最低

在进行 loong64 的特殊移植时，最让人头疼的莫过于我们针对 PKGBUILD 打的 loong.patch，在上游原仓库一有常规小更新时就会引发大面积的 Git merge 冲突。这也常常是让 AI 帮忙更新补丁时的问题——通用 AI 给出的补丁修复策略往往是“替换原数组某一行”，非常生硬。

为此笔者在 SKILL 定义了明确地修改安全范式：

永远优先追加（Append）：对于 makedepends、depends 或者是 source 哈希数组，必须使用 +=() 在文件尾部追加，即使上游把核心数组的顺序全改了也不受任何影响。
动态数组过滤：当碰到必须删除某些架构不支持的组件依赖（例如在国产平台上经常不需要的 cuda 组件时），不再直接去原生的声明列表里删词，而是建议通过 Bash 的 grep -Ev 对上游赋值完的数组进行尾部动态过滤。
代码段多行注释：不要删除无法使用的全段编译代码，而是用 : <<COMMENT ... COMMENT 将其完整包裹。

这可以使 AI 生成的移植补丁可以更加健壮。

为大规模依赖重构护航：Local Repo 自举链

当我们处理核心共享库升级带来的连带反应时，必须引入本地仓库作为引导桥梁。为此笔者在 SKILL 文件的进阶部分，完整传授了临时本地仓库的使用流程。告知 AI 如何借助 repo-add 工具以及编写带有优先级的 pacman 配置，从而引导其顺利通过诸如“包A -> 需依赖刚打出的包B -> 再编译新的包C” 这种 Bootstrap 的死锁链路，这一过程彻底解放了笔者的双手。

结语

通过将深度的领域知识转化为结构化的 SKILL 资产后，我惊讶地发现 AI 协助我们推进各种偏底层的系统组件适配效率实现了跨越式提升。原本排查 QEMU User 模式与真机引发各种诡异的 Segment fault 时只能抓瞎，但在有了完善的检查清单和路径指引下，它能够在正确的路径调用正确的工具做快速迭代。

只有基于严谨定义的专家心智模型，智能工具才能真正切中技术细节的痛点。这份 SKILL 文件不仅是对我们阶段性踩坑方案的记录，其实也是一部留给新人开发者的速成参考。未来，随着 LoongArch 整个新世界软生态的不断拓展，类似这样沉淀下来的系统化工程经验将持续发挥它们的指路作用。

附录：SKILL 内容完整再现

这套机制的完整规则可以直接在此阅读。你可以将它挂载到你自己的 AI Agent 或者 IDE 的环境设置中：

---
name: archlinux-loong64-portbuild
description: 'Assist with Arch Linux for Loong64 (loongarch64) package porting, building, and debugging using archbuild tools. Use when: porting packages to loong64, debugging archbuild or devtools-loong64 failures, fixing soname changes, etc., or patching PKGBUILDs.'
---

# Arch Linux for Loong64 构建与调试指南

你是一个精通 Arch Linux 软件包构建系统（特别是 `devtools` 和 `archbuild`）以及 LoongArch64 架构特性的专家。你的任务是协助用户理解构建流程、定位构建失败原因，并提供安全的调试方案和最适合的修复方案。

## 核心原则：环境隔离 (Environment Isolation)

**这是最重要的规则：**
1.  **宿主机是干净的**：`PKGBUILD` 所在的 Git 仓库目录**不包含**构建源码，也不应被用于直接编译或配置环境。
2.  **Chroot 是唯一的真相来源**：所有的源码下载、解压、编译、测试都发生在一个隔离的 systemd-nspawn 容器中。
3.  **绝不污染模板**：`/var/lib/archbuild/.../root` 是干净的模板环境，**绝对禁止**进入或修改它。如果它被污染，必须使用 `-c` 参数重建。

---

## 1. Archbuild 构建流程详解 (Mental Model)

当用户运行构建命令（如 `extra-loong64-build`）时，后台发生了以下流程。理解此流程是调试的关键：

1.  **环境准备**：
    *   系统读取干净的 chroot 模板（通常位于 `/var/lib/archbuild/extra-loong64-build/root`）。
    *   系统创建一个 Btrfs 快照或副本作为用户的工作区（位于 `/var/lib/archbuild/extra-loong64-build/<user-name>`）。
2.  **目录挂载**：
    *   宿主机的 `PKGBUILD` 所在目录（即 `pkgbase` 目录）被**只读挂载**到容器内的 `/startdir`。
    *   这意味着容器内可以看到 `PKGBUILD` 和 `loong.patch`，但无法修改它们。
3.  **源码获取与构建**：
    *   容器内的 `makepkg` 逻辑开始运行（以 `builduser` 用户身份）。
    *   源码被下载到 `/build/<pkgbase>/src/`。
    *   构建过程在 `/build/<pkgbase>/` 中进行。
4.  **清理与卸载**：
    *   构建结束后，`/startdir` 被卸载。
    *   如果构建成功，产物会被移回宿主机。
    *   用户工作区（`<user-name>`）通常会被保留，直到下次构建同仓库包时被覆盖或清理。

---

## 2. 关键路径映射表 (Path Mapping)

在指导用户时，请严格区分**宿主机路径**和**容器内路径**：

| 资源 | 宿主机路径 (Host) | 容器内路径 (Inside Chroot) | 备注 |
| :--- | :--- | :--- | :--- |
| **PKGBUILD 仓库** | `/path/to/pkgbase/` | `/startdir/` | 只读挂载，构建结束后卸载 |
| **构建工作区** | N/A | `/build/<pkgbase>/` | `builduser` 的家目录 |
| **源码目录** | N/A | `/build/<pkgbase>/src/` | 源码实际所在位置 |
| **构建产物** | N/A | `/build/<pkgbase>/pkg/` | 打包后的文件 |
| **用户 Chroot** | `/var/lib/archbuild/extra-loong64-build/<user>/` | `/` (根目录) | 完整的文件系统 |
| **干净模板** | `/var/lib/archbuild/extra-loong64-build/root/` | N/A | **禁止触碰** |

---

## 3. 标准调试工作流 (Debugging Workflow)

当构建失败，用户需要分析原因时，请引导用户遵循以下步骤，而不是在宿主机盲目猜测：

### 步骤 A：保存现场
默认情况下，下次构建可能会覆盖当前环境。建议用户先保存快照：
```bash
sudo btrfs subvolume snapshot /var/lib/archbuild/extra-loong64-build/<user-name> /path/to/snapshot
```

### 步骤 B：进入环境
使用 `systemd-nspawn` 进入出错的容器：
```bash
sudo systemd-nspawn -aD /path/to/snapshot
```
*注意：进入后默认是 root，需切换到构建用户：`sudo -u builduser bash`*

### 步骤 C：定位与分析
1.  进入构建目录：`cd /build/<pkgbase>/`
2.  查看源码：`ls src/`，检查 `src/` 下的文件结构。
3.  查看日志：检查 `build-log-all.log` （该文件不在容器内而是在 PKGBUILD 所在的宿主机目录下）或终端输出，确定失败发生在 `prepare()`, `build()`, 还是 `check()`。

### 步骤 D：修改与重测 (高级)
如果用户需要修改代码并重新测试（例如修改 `check()` 逻辑），由于 `/build/<pkgbase>/` 下没有 `PKGBUILD`，需要：
1.  将宿主机的 `PKGBUILD` 复制到容器内：`cp /startdir/PKGBUILD /build/<pkgbase>/` (如果 `/startdir` 还在) 或从外部复制。
2.  在 `/build/<pkgbase>/` 下运行：
    *   仅重跑检查：`makepkg --check`
    *   重新打包：`makepkg -R` (产物在 `/srcpkgdest/`)
*警告：此方法仅用于本地调试，生成的包严禁直接上传。*

### 步骤 E：处理 Git 仓库 (离开环境后)
`archbuild` 卸载 `/startdir` 后，容器内的 git 仓库会因为找不到 object 而报错。
*   **方案 1 (推荐)**：在启动 `systemd-nspawn` 时重新绑定挂载：
    `sudo systemd-nspawn -aD ... --bind /path/to/host/pkgbase:/startdir`
*   **方案 2**：修改 `.git/objects/info/alternates`，将 `/startdir` 替换为宿主机实际路径。

---

## 4. 常见问题排查思路 (Heuristics)

不要直接给出硬编码的修复代码，而是引导用户分析：

*   **Soname 变更**：
    *   检查日志中是否有 `==> Sonames differ in ...`。
    *   使用 `sogrep-loong64 -r all <lib.so>` 查找受影响的包。
*   **链接器错误 (Linker Errors)**：
    *   如果是 LTO 期间的段错误或 `R_LARCH_B26` 溢出，考虑是否因为某些原因没有覆盖到 `-mcmodel=medium`。
    *   也可能是链接器的 Bug，也许可以尝试切换链接器（如 `mold`）或临时禁用 LTO (`options=(!lto)`) 作为验证手段，而非永久修改。
*   **QEMU User 特异性问题**（仅对于在 QEMU User 模式下构建的包，在真机上运行时请忽略）：
    *   如果遇到诡异的卡死、超时或 `multiprocessing` 失败，提醒用户这可能是 QEMU User 模式的限制。
    *   建议在 QEMU System 或真机上复现以排除模拟层干扰。
    *   如果在真机上，即运行在 LoongArch64 硬件上，忽略 QEMU 相关的调试建议。
*   **补丁冲突 (Patch Conflicts)**：
    *   在维护 `loong.patch` 时，**优先使用追加 (`+=`) 而非修改原数组**。
    *   对于不需要的代码块，使用**多行注释** (`: <<COMMENT ... COMMENT`) 包裹，避免直接删除导致上游更新时冲突。

---

### 4.1 PKGBUILD 补丁策略详解：将冲突降至最低

在维护 `loong.patch`（针对 Arch Linux 官方 `PKGBUILD` 的补丁集）时，**核心原则是避免与上游日常更新产生 merge conflict**。由于我们维护的是补丁而非直接修改上游仓库，任何对原数组的直接修改都可能在上游升级时导致补丁失效。

#### 为什么优先追加而非修改？

上游维护者通常按字母顺序或逻辑分组来组织依赖数组。如果你直接在数组中间插入新元素，上游一旦调整顺序或添加新依赖，你的补丁就会冲突。

**正确做法：** 在 `PKGBUILD` 文件末尾使用 `+=` 追加元素，这样无论上游如何修改原数组，你的补丁都能稳定应用。

```bash
# 错误：直接修改原数组（容易冲突）
source=('upstream.tar.gz'
        'loongarch-fix.patch')  # 插入在这里，上游改顺序就冲突

# 正确：在文件末尾追加
source+=('loongarch-fix.patch')
sha256sums+=('xxx')  # 实际哈希值
```

同样的原则适用于其他数组：
```bash
# 在 PKGBUILD 末尾追加
makedepends+=('mold')
depends+=('some-loong64-specific-dep')
options+=('!lto')
```

#### 处理大段删除：使用多行注释

如果某个功能（如 CUDA 支持）在 loong64 上不可用，**直接删除代码会导致上游修改该函数时补丁冲突**。

**正确做法：** 使用 Bash 的多行注释语法 `: <<COMMENT_SEPARATOR ... COMMENT_SEPARATOR` 包裹不需要的代码：

```bash
# 在 PKGBUILD 中
build() {
    # ... 正常构建逻辑 ...

    # Use a "multi-line comment" to keep patch from rotting
    : <<COMMENT_SEPARATOR
    CFLAGS="${CFLAGS} -fno-lto" CXXFLAGS="${CXXFLAGS} -fno-lto" LDFLAGS="${LDFLAGS} -fno-lto" \
    cmake -B build-cuda -S $pkgname $_opts \
        -DCUDA_ARCH_BIN='...' \
        -DCUDA_ARCH_PTX='...'
    cmake --build build-cuda
COMMENT_SEPARATOR
}
```

如果不需要构建的内容在函数尾部，也可以直接插入 `return` 提前退出函数。

#### 动态过滤数组元素

对于 `pkgname`、`depends`、`makedepends` 等经常变动的数组，即使使用 `+=` 也无法解决"需要移除某些元素"的情况。**直接删除同样会冲突**。

**正确做法：** 在 `PKGBUILD` 末尾使用 `grep -Ev` 动态过滤：

```bash
# 从 pkgname 中移除不需要的子包
pkgname=($(printf "%s\n" "${pkgname[@]}" | grep -Ev '^(torchvision-cuda|python-torchvision-cuda)$'))

# 从 makedepends 中移除不需要的依赖
makedepends=($(printf "%s\n" "${makedepends[@]}" | grep -Ev '^(cuda|cudnn|python-pytorch-opt-cuda)$'))
```

这种方式的优势：
- 使用正则表达式 `^` 和 `$` 精确匹配，避免误删
- 灵活适配上游对数组顺序或内容的任何修改
- 补丁本身不依赖上游数组的具体结构

#### 处理 `pkgver()` 函数

如果 `pkgver()` 函数因环境差异导致版本号不一致（如 git hash 位数不同）：
- **不要**在 `loong.patch` 中修改 `pkgver` 变量
- **应该**注释掉 `pkgver()` 函数，使用上游提交的版本号
- **更好的做法**：向上游反馈，要求在 `git describe` 中添加 `--abbrev=12` 等参数以保证一致性（以"增加构建可复现性"为由）

---

## 6. 本地仓库 (Local Repo)：有依赖关系的顺序构建

### 6.1 使用场景与作用

在移植过程中，经常会遇到以下场景：

- **Soname 变更后的连锁重构**：上游升级导致 soname 变化，需要重新构建链接到它的包。这些包之间存在依赖关系，必须先构建并安装前面的包，后面的包才能正确链接。
- **Bootstrap 引导链**：某些包需要自身旧版本才能构建新版本，形成自举依赖。
- **批量打包后一次性上传**：社区规范要求依赖关系完整的包组必须一并上传，不能中途上传半成品到正式仓库。

**本地仓库的作用**：在本地创建一个临时的 pacman 软件源，按构建顺序逐个添加已打包的软件包，使后续包的构建过程能自动安装前面已构建好的依赖。这比手动传递 `-I` 参数给 `makechrootpkg` 更可靠、更可扩展。

### 6.2 建立本地仓库

```bash
sudo mkdir -p /srv/local-repo
sudo chown -R $USER:alpm /srv/local-repo
repo-add /srv/local-repo/local-repo.db.tar.gz
```

### 6.3 添加软件包到本地仓库

一个 `pkgbase` 构建完成后，其产生的**所有** `pkgname` 包（包括 debug 包以外的所有产物）必须**同时添加**到本地仓库。为简化操作，可封装脚本：

```bash
#!/bin/bash
# add-to-local: 批量添加包到本地仓库
if [ -z "$1" ]; then
  echo "Usage: $0 <db-file> <package1> [package2] ..."
  exit 0
fi

CURRENT_DIR=$(pwd)
DB_FILE="$1"
DB_DIR=$(dirname "$1")

shift
for pkg in "$@"; do
  pkg_basename=$(basename "$pkg")
  cp -f "$pkg" "$DB_DIR"
  if [[ "$pkg_basename" == *-debug-* ]]; then
    echo "Found debug package: $pkg_basename"
    continue
  fi
  cd "$DB_DIR"
  repo-add "$DB_FILE" "$pkg_basename"
  cd "$CURRENT_DIR"
done
```

使用方式：
```bash
add-to-local /srv/local-repo/local-repo.db.tar.gz /path/to/pkgbase/*.pkg.tar.zst
```

### 6.4 在 archbuild 中启用本地仓库

0. **先检查是否已启用，已启用就不要重复修改，跳过之后的步骤**：

```bash
CONF=/usr/share/devtools/pacman.conf.d/local-loong64.conf
if [ -f "$CONF" ] && grep -q '^\[local-repo\]' "$CONF" && [ -L /usr/bin/local-loong64-build ]; then
    echo "local-repo 已启用，跳过重复修改"
fi
```

1. **创建 pacman 配置**：在 `/usr/share/devtools/pacman.conf.d/` 下创建配置文件（如 `local-loong64.conf`），从 `extra-loong64.conf` 复制并编辑：

```bash
cp /usr/share/devtools/pacman.conf.d/extra-loong64.conf \
   /usr/share/devtools/pacman.conf.d/local-loong64.conf
```

2. **在配置文件中插入本地源**（**必须在所有其他源之前**）：

如果配置里已经存在 `[local-repo]` 段，**不要重复插入**。

```conf
[local-repo]
SigLevel = Never
Server = file:///srv/local-repo

# 下面是原有的源...
[core-loong64]
...
```

3. **创建 archbuild 软链接**（名称必须与 conf 文件对应）：

如果软链接已经存在，**不要重复创建**；可先检查再创建：

```bash
[ -L /usr/bin/local-loong64-build ] || sudo ln -s /usr/bin/archbuild /usr/bin/local-loong64-build
```

之后即可使用 `local-loong64-build` 命令进行构建，它会自动从本地仓库获取已构建好的依赖。

### 6.5 完整构建流程示例

使用 `genrebuild` 获取构建顺序后，按顺序逐个构建并添加到本地仓库：

```bash
# Bash 示例
for pkg in package1 package2 package3 ...; do
    get-loong64-pkg $pkg --skip-update
    cd $pkg
    gpg --import keys/pgp/*
    while ! updpkgsums; do :; done
    rm *.pkg.tar.zst*
    cd ..
    get-loong64-pkg $pkg --skip-update
    script -c "time local-loong64-build -- -- -A" build-log-all.log && \
        ../add-to-local /srv/local-repo/local-repo.db.tar.gz *.pkg.tar.zst
    if [ $? -ne 0 ]; then
        break
    fi
done
```

**全部构建成功后**，再将所有软件包一次性上传到正式仓库。完成后清空本地仓库：

```bash
rm -rf /srv/local-repo/*
repo-add /srv/local-repo/local-repo.db.tar.gz
```

### 6.6 注意事项

- **版本锁定问题**：如果本地仓库中有更新的包，但某个依赖锁定了旧版本，可能导致构建无效。可用 `pactree` 排查依赖关系。
- **上游 conf 更新后**：当 `devtools-loong64` 的 conf 文件更新后，需重新编辑 `local-loong64.conf` 同步上游变化。
- **`pkgrel` 批量修改**：按规范自动将 `pkgrel` 小数部分加 1：
  ```bash
  perl -i -pe 's{(^[^#]*?\bpkgrel\s*=\s*)(\d+)(?:\.(\d+))?}{$1 . $2 . "." . (defined($3) ? $3 + 1 : 1)}e' PKGBUILD
  ```

---

## 7. 标准构建命令

推荐用户使用 `script` 记录完整日志（包含 stderr 中的 `checkpkg` 输出）：

```bash
script -c 'time extra-loong64-build $(bash -c "source PKGBUILD; [[ \" \${arch[*]} \" =~ \" loong64 \" ]] || echo -- -- -A")' build-log-all.log
```

*   如果是本地仓库构建，将 `extra-loong64-build` 替换为 `local-loong64-build`。
*   参数 `-- -- -A` 用于在非 loong64 架构宿主机上强制构建 loong64 包（通过 QEMU User）。

---

## License

本 Skill 文件（`SKILL.md`）采用 **Creative Commons Attribution-ShareAlike 4.0 International (CC-BY-SA-4.0)** 发布。

完整许可证文本见 [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/)。

PvZ-Portable 输入系统与主循环优化：原生字符合成与 Web 端延迟修复

Mon, 23 Mar 2026 00:00:00 +0000

引言

在之前完成基于 Emscripten 的浏览器端适配后，PvZ-Portable 终于填补了跨平台版图的最后一块。引擎此时已经能在 PC、移动端乃至纯 Web 环境中跑通基础流程。但对于游戏移植而言，完成编译只是第一步，真正的考验在于如何抹平不同宿主环境对底层设施的入侵感。

在不同平台的细微体验打磨中，应用的输入处理和事件调度常常是重灾区。近期，笔者主要对 PvZ-Portable 的底层事件分发以及 Web 端主循环做了一次针对性的重构修复，进一步解决了跨系统开发中输入响应迟滞和事件派发错位等问题。本文将重点介这两项底层基础设施的优化细节。

Emscripten 主循环事件漏帧与鼠标拖动卡顿修复

在通过 Emscripten 编译到 Web 平台时，受限于浏览器的执行模型，传统的无限阻塞式游戏主循环必须被转换为异步的回调机制，通常挂载到浏览器的 requestAnimationFrame（rAF）中。

为了适配这一机制，PvZ-Portable 将原有的进程阻塞转编为一套状态机机制，通过 UpdateAppStep 函数逐步推进应用状态。然而，在之前的代码实现中，主循环的回调存在一个导致输入延迟和偶发掉帧的判定问题，其最典型的症状是：在 Web 端游戏内拖动鼠标时，画面会出现明显的卡顿甚至完全冻结。

// 旧版轮询逻辑
while (updated || app->mUpdateAppState == UPDATESTATE_PROCESS_2 || app->mHasPendingDraw)
{
    if (!app->UpdateAppStep(&updated))
        break;

    if (!updated && app->mUpdateAppState == UPDATESTATE_PROCESS_DONE && !app->mHasPendingDraw)
        break;
}

这段代码的问题在于对其状态穷举不足。在特定的中间状态下，如果在当前迭代中没有产生明显的逻辑更新（updated 为 false），循环会提前 break，将剩余的事件处理或帧渲染推迟到下一个 rAF 回调。

当玩家快速移动或拖动鼠标时，底层会产生大量的 SDL_MOUSEMOTION 事件，而这种提前 break 的机制导致引擎无法在一个单独的浏览器刷新帧内将堆积的鼠标事件完全消化。未处理的事件导致事件队列拥塞，状态机因为事件迟滞而无法推进，反映在游戏体验上便是严重的拖放卡顿感。

优化方案是将终止条件改为显式校对最终完成状态，强制事件泵在单次浏览器帧回调内彻底排空所有挂起阶段和积压事件：

// 优化后的 Emscripten 轮询逻辑
while (app->mUpdateAppState != UPDATESTATE_PROCESS_DONE || app->mHasPendingDraw)
{
    if (!app->UpdateAppStep(&updated))
        break;
}

通过这一改动，只要引擎没有抵达 UPDATESTATE_PROCESS_DONE，状态机就会在其所在的这一个 rAF 内部不间断推进。所有的用户输入堆栈（包括高频次触发的鼠标移动操作）和挂起的绘制指令都能在一个物理周期内高效率地提取并结算。更新此逻辑后，Web 端鼠标拖放的卡顿问题得到了彻底解决。

SDL2 原生字符合成与作弊快捷键修复

原版游戏及引擎中存在许多依赖于 KeyChar 键盘事件直接触发的动作交互，其中就包含了游戏内丰富的作弊快捷键（-DPVZ_DEBUG且启动时传递-tod参数时开启）。

在现代的跨平台 SDL2 开发范式中，上层若想获取标准的对应字符级事件，常规的做法是调用 SDL_StartTextInput()。但这在许多非传统桌面系统平台中会引发不符合预期的副作用：无论是在移动设备上还是包含虚拟键盘的现代桌面环境，拉起标准的 Text Input 上下文会不可避免地强制唤起输入法辅助面板，甚至直接拉长屏幕占用遮挡半个游戏视野。

然而我们仅仅是想让玩家在游戏正常流程下顺畅使用那些老式的单键快捷组合。引擎需要一种能在不触发系统输入法弹窗的前提下，静默且准确地提取字符事件的方案。

由于这部分快捷键纯粹属于字符组合与映射操作，笔者在 SDL 事件泵处理 SDL_KEYDOWN 的逻辑中建立了一个底层的 ASCII 字符合成器，从物理按键及其修饰符直接向游戏应用派发所需的 KeyChar 信息：

static bool SDLSynthesizeAsciiCharFromKeyDown(const SDL_KeyboardEvent& theEvent, char& theChar)
{
    theChar = 0;

    // 当游戏真正需要文本输入（如存档命名）时，让位给系统的系统输入法
    if (SDL_IsTextInputActive())
        return false;

    SDL_Keycode aSym = theEvent.keysym.sym;
    SDL_Keymod aMods = static_cast<SDL_Keymod>(theEvent.keysym.mod);
    const bool aHasCtrl = (aMods & KMOD_CTRL) != 0;
    const bool aHasAlt = (aMods & KMOD_ALT) != 0;
    const bool aHasGui = (aMods & KMOD_GUI) != 0;
    const bool aHasShift = (aMods & KMOD_SHIFT) != 0;

    // 过滤掉包含 Alt 或 Gui 中继键的操作
    if (aHasAlt || aHasGui)
        return false;

    // 映射字母并处理 Shift 组合
    if (aSym >= SDLK_a && aSym <= SDLK_z)
    {
        theChar = aHasCtrl
            ? static_cast<char>(aSym - SDLK_a + 1)
            : static_cast<char>(aHasShift ? aSym - SDLK_a + 'A' : aSym);
        return true;
    }

    if (aHasCtrl)
        return false;

    // 映射数字区域与其他标点符号
    switch (aSym)
    {
        case SDLK_1: theChar = aHasShift ? '!' : '1'; return true;
        // ... (其他字符映射省略)
        case SDLK_SPACE: theChar = ' '; return true;
        default: return false;
    }
}

随后在事件循环处理 SDL_KEYDOWN 的分支处增加对合成器的调用：

case SDL_KEYDOWN:
{
    mLastUserInputTick = mLastTimerTime;
    mWidgetManager->KeyDown(SDLKeyToKeyCode(event.key.keysym.sym));

    char aSynthesizedChar = 0;
    if (SDLSynthesizeAsciiCharFromKeyDown(event.key, aSynthesizedChar))
        mWidgetManager->KeyChar(aSynthesizedChar);

    break;
}

在此流程下，当玩家敲击键盘时，普通的字符映射被自动合成为 KeyChar 信息传递给 WidgetManager 控制层。游戏内部对于键盘流的监听与原版无缝衔接，同时通过判断 SDL_IsTextInputActive()，保留了玩家建立新存档需要输入账号名称时的正常虚拟键盘唤起通道，互不冲突。

结语

不同运行环境的差异往往体现在 API 缝隙以及系统调用习惯上。通过修正 Emscripten 帧回调中的提前退出机制，以及解耦字符获取机制与 OS 输入法组件之间的强绑定，PvZ-Portable 进一步消除了不同平台的体验差异。游戏引擎的基础设施改进仍在继续进行中。

⚠️ 版权与说明

重要：本项目仅包含代码引擎，不包含任何游戏素材！

PvZ-Portable 严格遵守版权协议。游戏的 IP（植物大战僵尸）属于 PopCap/EA。

main.pak
properties/ 目录

本项目的源代码以 LGPL-3.0-or-later 许可证开源，欢迎学习和贡献。

Qt Web Extractor：轻量级的跨平台网页内容提取工具

Fri, 20 Mar 2026 00:00:00 +0000

网页内容提取的痛点

目前给 LLM 平台提供网页提取或者搜索功能的 API 一般依赖于 Playwright 或 Puppeteer 等技术。这些技术十分强大，能够完美处理动态网页，但也带来了一个显著的问题：过于笨重。

它们通常要求在使用时下载体积庞大的独立完整浏览器二进制文件，在运行时也需要启动完整的浏览器进程。对于一套仅仅用来抓取文本的后端服务来说，这不仅占用了较多的磁盘存储和执行内存，在不同环境部署时也显得有些麻烦。

更为棘手的问题在于跨架构的支持。笔者同时担任着 Arch Linux for Loong64 的维护者，在适配 LoongArch 架构时深有体会。这其实是双重的挑战：首先，像 Playwright 这样的工具本身在 LoongArch 下从源码构建就困难重重，笔者至今也没有成功构建出其稳定可用的版本；其次，它们在运行时强依赖于上游官方预编译发布的 Chromium 等独立浏览器二进制文件，而官方并没有提供针对 LoongArch 等非主流架构的打包分支，这让常规的方法很困难。

在这样的背景下，笔者开发了 qt-web-extractor 项目。项目的核心目标是打造一个简单、易用、轻量且真正跨平台的通用网页内容提取工具。在 Linux、Windows、macOS 在内的各平台上都能轻松部署运行，不再受限于强绑定的独立浏览器二进制文件；同时，它也顺带完美解决了前文所述的跨指令集架构难题——可以直接使用发行版提供的 Qt WebEngine 库。

为什么选择 Qt WebEngine

既然需要一个能解析 JavaScript、执行客户端动态渲染并且高度跨平台的轻量级替代方案，Qt WebEngine 成为了极佳的选择。

Qt WebEngine 本质上是 Chromium 的封装，前端渲染和 JS 执行能力与现代浏览器完全一致。它本身就是一个极其成熟及通用的跨平台基础构件，只需引入对应的 Python 绑定包 PySide6，即可直接作为轻量的提取引擎工作，免去了繁琐的额外配置。

而在 Linux 平台下，它还额外带来了得天独厚的优势：作为非常通用的基础 GUI 依赖，从 x86 到 LoongArch、RISC-V 等各种指令集的分支，几乎所有的主流发行版都已经把它在软件仓库中打包集成好了。如果在 Linux 下使用，它可以直接复用系统的动态库，无需再去第三方服务器下载动辄好几百兆的 Chromium 内核。只要用常规的包管理器备齐环境，部署本项目几乎不会带来任何额外的存储占用开销。

Qt Web Extractor 简介

Qt Web Extractor 是一个基于 Qt WebEngine 和 Qt PDF 实现的通用网页内容提取工具。它通过 Qt 的 offscreen 模式实现无头运行，不需要显示器或显卡参与渲染，专门用于解决提取那些依赖 JavaScript、由客户端动态加载渲染的现代网页内容，弥补普通 HTTP 请求无法执行 JS 的短板。

项目仅依赖于 PySide6 与 Qt6 WebEngine 模块，方便部署。

核心特性

全面的 JavaScript 渲染支持：对于常见的单页应用或客户端渲染构建的页面，普通的 requests 纯 HTTP 请求只能获取基础的 HTML 代码。本项目会等待页面渲染完毕，返回包含实际完整内容的纯文本或 DOM 代码。
多种使用接口：提供命令行工具、Python 模块 API，以及内置的 HTTP REST API 服务。
通用的 HTTP API：服务端常驻后台后，能为各类 AI 平台、监控脚本等提供统一的页面与文本获取服务。同时，它还开箱即用支持被配置为 Open WebUI 的外部网页加载器，源码目录中也包含了作为对话自定义工具引用的脚本。
原生 PDF 解析：这个扩展特性针对的是一个非常影响现实体验的痛点。之前笔者发现在 Open WebUI 中，如果 LLM 使用 Open WebUI 自带的默认提取器去调取一个 PDF 类型的链接，会把 PDF 的二进制格式文件直接拉下来，然后当成文本直接塞到对话的上下文中。这可以说是一场灾难，模型不仅获取其中的有效信息，还会浪费巨量 Token。而在本机提取中，遇到 PDF 文件时，可以直接利用与 Qt WebEngine 搭配的 Qt PDF 库将文件中的真正可读文本层解析、提取并返回，完美解决了这个十分影响用户体验的痛点。
部署极简：依赖简洁且不需要独立下载浏览器，提供 systemd 服务文件和基于 AUR 的部署方式，安装和后台启停都非常方便。

使用方式展示

常驻 HTTP 服务

工具最常见的使用方式是作为后端的公共常驻服务。项目内置了 HTTP 服务器：

qt-web-extractor serve --host 127.0.0.1 --port 8766 --api-key mysecretkey

启动以后，它就可以作为一个通用的 REST API 供其他程序调用。例如在 Open WebUI 的管理后台中，将 Web Loader Engine 设置为 external，填写这个地址和配置好的 API Key。此后环境中所有的网页阅读、数据拉取都会交由它进行渲染分析。因为能执行 JS 的缘故，它自然也可以顺利加载更多的网页（比如通过简单 HTTP 访问不能获取的知乎、Hugging Face 等等），并且能在应对含有弹窗或单页路由的页面时获取到渲染后的实际 DOM 文本。

命令行工具

通过命令行可以直接快速提取目标源并将结果输出到终端：

# 纯文本提取
python -m qt_web_extractor https://example.com

# 输出 JSON 格式
python -m qt_web_extractor --json https://example.com

# 提取渲染后的 HTML 代码
python -m qt_web_extractor --html https://example.com

# 解析 PDF 文本
python -m qt_web_extractor https://example.com/document.pdf

Python 代码调用

项目本身也是一个标准的 Python 包：

from qt_web_extractor import QtWebExtractor

extractor = QtWebExtractor(timeout_ms=30000)
result = extractor.extract("https://example.com")

print(result.text)   # 提取经过渲染的网页纯文本
print(result.html)   # 提取渲染后的 HTML

工具引擎在主线程运行 Qt 的事件循环，通过后台线程处理 HTTP 接口。面对每次请求，会在网页完成加载后再给出一定的缓冲时间保证 JS 执行完毕，确保提取的是最终视图数据。

总结

Qt Web Extractor 通过系统自带的 Qt WebEngine 来进行加载和提取，既保留了执行现代前端框架必备的 Chromium 核心能力，又规避了平台架构支持的局限和额外的存储烦恼。

如果你也面临特殊指令集的部署难题或者厌倦了总是要下载臃肿的浏览器环境，可以尝试一下这个极简的方案。在 Arch Linux 上可以通过 AUR 直接安装包。

项目仓库地址：GitHub · Qt Web Extractor

项目协议：GPL-3.0-or-later

星外之神 Blog

LinSYS2：无需虚拟机与容器，在Linux上完整管理、构建、调试与运行Windows程序

前言

LinSYS2是什么

核心特性一览

安装

Arch Linux

其他发行版

快速上手：两条命令开始Windows开发

典型工作流

初始化环境与同步数据库

安装开发工具链

编译与调试

交互式Shell

多环境切换

与现有Wine集成

技术实现要点

为什么必须使用MSYS2 pacman fork

包格式与数据库的跨平台兼容性

Wine前缀管理与环境注入策略

独立WINEPREFIX模式（默认推荐）

现有Wine环境集成

用户级隔离与零系统冲突

.install Scriptlet与Hook的处理

横向对比总结

结语

Qt Web Extractor：适配 Anubis 并与 Qt HTML 解析斗智斗勇

背景

Anubis：其实适配很简单

现象

分析

修复

Qt HTML 解析的内存失控

现象

定位

尝试与回退

与大页面内存问题的交叉影响

内容丢失问题

checkVisibility 的误判

DOM 遍历范围的遗漏

总结

PvZ-Portable：跨平台光标系统的 SDL 实现与自定义光标缓存

引言

被遗留的 Windows 光标实现

跨平台重构：下沉到 SexyAppBase

系统光标映射

从 MemoryImage 到 SDL_Cursor

缓存策略与性能优化

系统光标缓存

自定义光标缓存

隐藏光标与状态管理

结语

⚠️ 版权与说明

PvZ-Portable：长期运行稳定性修复——从计数器溢出到浮点精度悬崖

引言

浮点精度

精度衰减时间表

int32_t 溢出的未定义行为

计数器类型重构

将主计数器切换为 uint32_t

统一派生计数器

存档同步路径的适配

动画相位的周期性取模

浓雾动画（Fog）

弹坑水波（Crater）

宝石迷阵旋转效果

漂浮植物与咖啡豆

泳池波动（PoolEffect）

闪烁颜色与 abs 的安全性

数据一览

回绕对齐的缺陷

结语

⚠️ 版权与说明

PvZ-Portable 资源释放时序安全：动画附件生命周期与 SDL 音频回调的硬防护

引言

Reanimator 动画附件的生命周期治理

崩溃现象与排查方向

Atlas 语义修正：区分编码句柄与真实指针

附件系统的释放

投石车僵尸的调用侧修正

`.install` Scriptlet与Hook的处理

`int32_t` 溢出的未定义行为

将主计数器切换为 `uint32_t`

闪烁颜色与 `abs` 的安全性

向 `std::vector` 重构与追加前 flush

隐藏已久的 `delete`/`delete[]` 不匹配