简介面向 Linux 桌面用户与开发者的一款 CHM 文档阅读工具源码包解决 Linux 系统原生无法直接打开微软编译的 CHM 帮助文件这一痛点尤其适合需要频繁查阅中文技术手册、离线帮助文档的读者。压缩包共 111 个文件约 355KB以 C 源码与头文件为主体辅以 configure、Makefile.am 等构建脚本以及 glade 界面描述、po 翻译、desktop 与 mime 注册文件、图标图片和说明文档构成一套可编译安装的完整工程。已有 468 人学习下载。包内保留 chmsee 的解析与索引实现、多语言支持、全文搜索、书签与右键菜单等特性代码读者可据此了解 CHM 解析流程、Firefox 插件集成方式及依赖库配置思路也便于在本地编译、改造或移植到不同发行版是研究 Linux 下文档阅读器实现的一份轻量参考。1. chmsee 在 Linux 上读 CHM一个被低估的老工具为什么还值得装手头拿到一份 CHM 格式的技术手册双击在 Linux 桌面里没反应右键菜单里也找不到能打开的程序——这种场景在运维和嵌入式岗上并不少见。CHM 是微软早年那套 HTML Help 编译出来的单文件格式内部是 LZX 压缩的 HTML、图片和索引Windows 上自带阅读器Linux 这边就得自己找工具。chmsee 就是这类工具里比较老牌的一个基于 GTK 的图形界面阅读器底层用 chmlib 解析容器能把目录树、全文索引和正文渲染出来。它解决的不是「转换格式」而是「就地阅读」——不拆包、不联网、不依赖浏览器插件适合需要频繁翻查离线手册、又不想为一份文档装一整套重量级套件的人。这篇按「它靠什么工作 → 怎么装怎么用 → 哪里会翻车」的顺序拆新手能照着跑通熟手能看清它的边界在哪。2. chmsee 的解析链路chmlib 怎么把 CHM 拆成可读页面2.1 CHM 容器结构与 chmsee 的读取顺序要判断 chmsee 适不适合你的场景先得知道它拿到一个 .chm 文件后干了什么。CHM 本质是一个带索引的复合容器文件头之后是若干「内容段」其中#ITSF头描述整体布局#ITSP是段表#ITSL是 LZX 压缩数据的定位表#IVB记录目录树结构#SYSTEM存标题、默认页、窗口尺寸这类元信息。chmsee 并不自己实现解压它把容器解析交给 chmlib自己只负责三件事向 chmlib 要目录树、要指定路径的原始字节、把字节按 HTML 渲染到 GTK 的 WebView 里。读取顺序大致是先读#SYSTEM拿到默认首页路径和编码提示再读#IVB构建左侧目录树用户点某个节点时chmsee 把该节点对应的内部路径形如/manual/ch01.html交给 chmlib 的chm_retrieve_object拿回解压后的字节流然后判断内容类型——HTML 走渲染图片走解码CSS 直接注入。这个链路决定了它的能力边界凡是 chmlib 能正确解压的段chmsee 就能显示chmlib 解不动的比如某些非标准 LZX 变体或加密段界面上就是空白或报错。提示判断一个 CHM 能不能被 chmsee 打开最省事的办法是先用命令行工具extract_chmLib试抽一个文件出来抽得动基本就能读抽不动就别在 GUI 上反复试了。2.2 依赖栈与安装路径的选择chmsee 的依赖不算轻但都是发行版仓库里的常规包GTK 2.x老版本或 GTK 3较新分支、WebKitGTK 作为渲染引擎、chmlib 做容器解析、libgcrypt 处理校验。不同发行版的包名差异很大装之前先确认仓库里有没有现成包没有再从源码编。下面这套流程是我在 Debian 系上跑通的其他系把包管理器命令换掉即可。# 先查仓库里有没有现成包有就直接装别急着编译 apt-cache search chmsee # 若返回结果为空安装编译依赖Debian/Ubuntu 系 sudo apt-get install build-essential pkg-config \ libgtk-3-dev libwebkit2gtk-4.0-dev libchm-dev libgcrypt20-dev \ intltool autoconf automake libtool这段命令的逻辑是第一步只做查询避免明明有二进制包却去折腾源码第二步把编译期需要的头文件和工具一次装齐其中libchm-dev提供 chmlib 的头文件libwebkit2gtk-4.0-dev提供渲染引擎intltool和autoconf系列是 autotools 构建链的必需品。参数上没什么可调的唯一要注意的是 WebKitGTK 的版本号——4.0 和 4.1 是两套 ABI源码里configure.ac写死哪一个就得装哪一个装错了会在链接阶段报 undefined reference。源码构建的标准三步走# 在源码根目录执行先生成 configure 脚本 ./autogen.sh # 指定安装前缀装到 /usr/local 避免污染系统包 ./configure --prefix/usr/local # 并行编译核数按机器来 make -j$(nproc) sudo make install--prefix/usr/local是我习惯的做法好处是卸载时直接删目录不会和包管理器打架代价是ldconfig缓存里可能找不到新库首次运行若报error while loading shared libraries执行一次sudo ldconfig即可。make -j$(nproc)里的nproc返回逻辑核数编译 chmsee 这种规模的项目四核机器一两分钟就完事没必要开太高并行度反而抢内存。2.3 首次启动与界面元素的实际含义装完直接敲chmsee启动界面分三块左侧目录树、右侧正文区、顶部工具栏。打开文件走「文件 → 打开」或者命令行直接带路径chmsee /path/to/manual.chm。这里有个容易被忽略的点chmsee 的目录树读的是#IVB段如果某份 CHM 的制作者用了非标准的目录结构常见于用第三方工具二次打包的文档左侧可能是空的但正文仍能通过「首页」按钮或手动输入内部路径访问。工具栏上的「后退/前进」是基于内部路径的历史栈不是浏览器那种完整会话恢复「查找」只搜当前页面文本不做全书索引检索——这是它和商业阅读器最大的功能差距。如果你的诉求是「在几百页手册里全文搜关键词」chmsee 帮不上忙得换思路后面第 5 章会讲怎么用外部工具补这块。但如果只是「按目录翻、看图文混排的章节」它的渲染质量在同类里算稳的尤其是表格和代码块的排版比一些纯文本抽取工具强不少。3. 把 chmsee 用顺手打开、导航与内容抽取的实操3.1 命令行打开与批量处理图形界面点开只是入门真正提效的是命令行组合。chmsee 接受文件路径参数这意味着可以配合find做批量打开或者写进脚本按项目目录自动加载对应手册。# 找出当前项目下所有 chm 文件并逐个打开适合手册分散在多个目录的情况 find ~/docs -name *.chm -type f | while read -r f; do echo 打开: $f chmsee $f done这段脚本的关键在chmsee 是 GUI 程序不加后台符号会阻塞循环导致只有第一个文件被打开。read -r的-r参数防止反斜杠被转义路径里带空格或特殊字符时更安全。实际用的时候建议加个sleep 1避免瞬间拉起十几个窗口把桌面卡住——血泪经验第一次批量开二十份手册机器直接假死了半分钟。如果只是想快速确认某份 CHM 的元信息标题、默认页、是否有目录不必开 GUI用 chmlib 自带的工具更轻# 列出 CHM 内部所有对象路径相当于看容器里装了哪些文件 extract_chmLib manual.chm /tmp/chm_dump -l # 只抽 #SYSTEM 段看元信息十六进制可读字符混合输出 extract_chmLib manual.chm /tmp/chm_dump -s-l是 list 模式只列路径不写文件输出里能看到/xxx.html、/images/yyy.png这样的内部结构据此判断目录树是否完整-s抽的是系统段输出里夹着可读字符串能快速确认文档标题和编码声明。这两个命令在排查「为什么 chmsee 打开是空白」时特别有用——先确认容器本身能不能读再怀疑渲染层。3.2 目录树异常与编码问题的处理中文 CHM 最常见的翻车点是乱码。原因有两层一是 CHM 内部 HTML 的meta charset声明和实际字节编码不一致制作者用 GBK 存内容却声明 UTF-8或反过来二是 chmsee 的渲染引擎按声明走声明错了就整页乱码。处理办法是先抽一页出来看真实编码# 抽取单个 HTML 对象用 file 命令探测真实编码 extract_chmLib manual.chm /tmp/chm_dump /index.html file -i /tmp/chm_dump/index.htmlfile -i输出形如text/html; charsetgbk这就是真实编码。如果和页面声明不符chmsee 界面上没有强制指定编码的选项老版本的短板可行的绕法是用iconv把抽出来的整份文档转成 UTF-8 再本地打包成一份新的 CHM或者干脆放弃 CHM 形态转成 HTML 目录用浏览器读。后者更省事第 5 章会给完整脚本。目录树为空则是另一类问题多半是#IVB段结构非标准。判断方法还是extract_chmLib -l如果列出的路径里有.hhc文件HTML Help 的目录定义文件说明目录信息在只是 chmsee 没解析出来这时可以手动抽.hhc看结构或者直接用正文区的「首页」按钮逐页翻。这类文档不多但遇到一次就够折腾提前用-l探一遍能省不少时间。3.3 从阅读到抽取把 CHM 转成可检索的本地文档chmsee 的定位是「读」不是「转」。但实际工作里读完往往要引用、要搜索、要归档这时候就得把内容抽出来。chmlib 的extract_chmLib是现成的抽取器配合find和sed能把整份 CHM 摊平成普通 HTML 目录。# 把整份 CHM 抽到指定目录目录不存在会自动建 mkdir -p /tmp/manual_html extract_chmLib manual.chm /tmp/manual_html # 统计抽出的文件数和总体积确认没有中途失败 find /tmp/manual_html -type f | wc -l du -sh /tmp/manual_htmlextract_chmLib的第二个参数是输出目录第三个参数可选指定只抽某个对象不给就全抽。抽完之后目录结构基本还原了 CHM 内部的路径层级HTML 之间的相对链接大多还能用直接用浏览器打开入口页就能读。这一步的价值在于抽出来的 HTML 可以被grep、被全文索引工具扫、被版本控制管理chmsee 做不到的「全书搜索」在这里补上了。注意抽取出来的 HTML 里可能残留ms-its:这类 Windows 专有协议链接指向 CHM 内部其他对象。浏览器不认这种协议点了没反应。批量替换成相对路径即可sed -i s|ms-its:[^:]*::|/|g能处理大部分情况替换前先备份。4. 避坑清单chmsee 装不上、打不开、显示错的五类现场4.1 编译期报 WebKit 头文件找不到现象./configure阶段报Package webkit2gtk-4.0 was not found但明明装了libwebkit2gtk-4.0-dev。原因通常是pkg-config的搜索路径没包含该包的.pc文件或者装的是 4.1 版本而源码要 4.0。解决先pkg-config --list-all | grep webkit确认实际可用的包名再对照configure.ac里的PKG_CHECK_MODULES行版本对不上就装对应版本的 dev 包路径问题则export PKG_CONFIG_PATH/usr/lib/x86_64-linux-gnu/pkgconfig:$PKG_CONFIG_PATH后重跑 configure。4.2 运行时报共享库缺失现象chmsee: error while loading shared libraries: libchm.so.0: cannot open shared object file。原因是源码装到了/usr/local/lib但动态链接器缓存没更新。解决sudo ldconfig刷新缓存若仍不行检查/etc/ld.so.conf.d/下有没有包含/usr/local/lib的配置没有就补一行再ldconfig。这类问题在自定义 prefix 安装时几乎必现养成装完就跑一次ldconfig的习惯能省很多排查时间。4.3 打开 CHM 后正文区全白现象目录树正常点节点正文区一片空白。原因分两种一是该页面的 HTML 引用了外部资源如http://开头的图片或样式离线环境下加载失败导致渲染中断二是页面编码声明错误渲染引擎解析失败。解决先用extract_chmLib抽出该页file -i看编码编码对就用文本编辑器打开看有没有外链引用有的话批量替换成本地相对路径或直接删掉引用标签。判断顺序永远是「先容器后渲染」别一上来就怀疑 chmsee 本身。4.4 中文显示成方块或问号现象正文能渲染但中文全是方块。原因是系统缺中文字体WebKitGTK 找不到可用字形就画方块。解决装一套中文字体如fonts-noto-cjk然后fc-cache -fv刷新字体缓存。这个坑和 chmsee 无关任何基于 WebKit 的阅读器在精简系统上都会遇到装完字体重启程序即可。顺带一提字体装全了之后代码块里的等宽字体渲染也会更正常算是一举两得。4.5 大文件打开卡顿甚至无响应现象打开几十 MB 的 CHM 时界面卡住进度条不动。原因是 chmsee 在构建目录树时同步读取#IVB大文档的目录节点多主线程被占满。解决先用extract_chmLib -l确认文件规模节点数上千的话别指望 GUI 流畅直接走抽取路线用浏览器读如果非要 GUI启动后耐心等目录树加载完再操作中途点击会加剧卡顿。这类性能问题没有配置项可调属于工具设计上的边界认清它比硬扛更实际。5. 进阶用抽取脚本把 CHM 变成可全文检索的本地知识库chmsee 读单份文档够用但当你手上有十几份 CHM 手册、需要跨文档搜一个 API 名或错误码时GUI 逐个翻就太慢了。我的做法是用extract_chmLib批量摊平再用一个轻量索引脚本把 HTML 转成纯文本并建倒排索引最后用grep -r或ripgrep直接搜。整套流程不需要额外服务纯命令行适合放在项目目录里随用随跑。先写批量抽取脚本处理多份 CHM 并统一输出结构#!/usr/bin/env bash # batch_extract.sh把指定目录下所有 CHM 抽到独立子目录 set -euo pipefail SRC_DIR${1:?用法: $0 chm目录 输出目录} OUT_DIR${2:?用法: $0 chm目录 输出目录} mkdir -p $OUT_DIR find $SRC_DIR -name *.chm -type f | while read -r chm; do # 用文件名去扩展名作为子目录名避免不同手册互相覆盖 base$(basename $chm .chm) target$OUT_DIR/$base mkdir -p $target echo 抽取 $chm - $target # 单份失败不中断整体流程 extract_chmLib $chm $target || echo 警告: $chm 抽取失败跳过 doneset -euo pipefail让脚本在管道任一环节出错时立即退出避免半途而废留下脏数据${1:?...}是参数校验缺参数直接报用法而不是静默跑错目录。|| echo那行是刻意放宽的单份 CHM 损坏不应该拖垮整批任务记录警告继续跑更符合实际。输出目录按文件名分子目录是因为不同手册内部路径经常重名都有/index.html混在一起会互相覆盖。抽取完的 HTML 里混着标签直接grep会命中大量无关的 class 名和脚本。加一步转纯文本# 用 python 标准库做 HTML 转文本不引入第三方依赖 python3 - PY import pathlib, re, html root pathlib.Path(/tmp/manual_html) for p in root.rglob(*.htm*): raw p.read_text(encodingutf-8, errorsignore) # 去掉 script/style 块再去标签最后反转义实体 raw re.sub(r(script|style)[^]*.*?/\1, , raw, flagsre.S|re.I) text re.sub(r[^], , raw) text html.unescape(text) text re.sub(r\s, , text).strip() p.with_suffix(.txt).write_text(text, encodingutf-8) print(转换完成) PY这段 Python 的逻辑是三步清洗先整块删掉script和style这两类内容对检索毫无价值还特别占体积再用正则把剩余标签替换成空格不是删掉避免相邻单词粘连最后html.unescape把amp;这类实体还原成字符\s压缩连续空白。errorsignore是兜底前面编码问题没处理干净的页面不至于让脚本崩掉。转出来的.txt和原 HTML 同目录用rg搜的时候加-g *.txt限定范围即可。实际检索时我一般这样用# 在所有转出的文本里搜关键词显示文件名和行号 rg -n -g *.txt 错误码 E1024 /tmp/manual_html # 只统计哪些手册命中快速定位该翻哪一份 rg -l -g *.txt E1024 /tmp/manual_html | xargs -n1 dirname | sort -u-l只输出命中文件名配合xargs dirname和sort -u就能得到「哪几份手册提到过这个错误码」的清单比逐个打开 chmsee 翻目录快一个数量级。这套组合的边界也很清楚它做的是字面匹配不理解语义同义词和拼写变体搜不到但对技术手册这种术语固定的材料字面检索的命中率已经足够高。从那以后我每次拿到一批 CHM都强制先跑一遍extract_chmLib -l探容器、再批量抽取转文本确认索引建好之后才决定要不要开 GUI 精读——这个顺序帮我避开了好几次「打开是空白还以为文件坏了」的乌龙。希望帮到你。本文还有配套的精品资源点击获取
简介面向 Linux 桌面用户与开发者的一款 CHM 文档阅读工具源码包解决 Linux 系统原生无法直接打开微软编译的 CHM 帮助文件这一痛点尤其适合需要频繁查阅中文技术手册、离线帮助文档的读者。压缩包共 111 个文件约 355KB以 C 源码与头文件为主体辅以 configure、Makefile.am 等构建脚本以及 glade 界面描述、po 翻译、desktop 与 mime 注册文件、图标图片和说明文档构成一套可编译安装的完整工程。已有 468 人学习下载。包内保留 chmsee 的解析与索引实现、多语言支持、全文搜索、书签与右键菜单等特性代码读者可据此了解 CHM 解析流程、Firefox 插件集成方式及依赖库配置思路也便于在本地编译、改造或移植到不同发行版是研究 Linux 下文档阅读器实现的一份轻量参考。1. chmsee 在 Linux 上读 CHM一个被低估的老工具为什么还值得装手头拿到一份 CHM 格式的技术手册双击在 Linux 桌面里没反应右键菜单里也找不到能打开的程序——这种场景在运维和嵌入式岗上并不少见。CHM 是微软早年那套 HTML Help 编译出来的单文件格式内部是 LZX 压缩的 HTML、图片和索引Windows 上自带阅读器Linux 这边就得自己找工具。chmsee 就是这类工具里比较老牌的一个基于 GTK 的图形界面阅读器底层用 chmlib 解析容器能把目录树、全文索引和正文渲染出来。它解决的不是「转换格式」而是「就地阅读」——不拆包、不联网、不依赖浏览器插件适合需要频繁翻查离线手册、又不想为一份文档装一整套重量级套件的人。这篇按「它靠什么工作 → 怎么装怎么用 → 哪里会翻车」的顺序拆新手能照着跑通熟手能看清它的边界在哪。2. chmsee 的解析链路chmlib 怎么把 CHM 拆成可读页面2.1 CHM 容器结构与 chmsee 的读取顺序要判断 chmsee 适不适合你的场景先得知道它拿到一个 .chm 文件后干了什么。CHM 本质是一个带索引的复合容器文件头之后是若干「内容段」其中#ITSF头描述整体布局#ITSP是段表#ITSL是 LZX 压缩数据的定位表#IVB记录目录树结构#SYSTEM存标题、默认页、窗口尺寸这类元信息。chmsee 并不自己实现解压它把容器解析交给 chmlib自己只负责三件事向 chmlib 要目录树、要指定路径的原始字节、把字节按 HTML 渲染到 GTK 的 WebView 里。读取顺序大致是先读#SYSTEM拿到默认首页路径和编码提示再读#IVB构建左侧目录树用户点某个节点时chmsee 把该节点对应的内部路径形如/manual/ch01.html交给 chmlib 的chm_retrieve_object拿回解压后的字节流然后判断内容类型——HTML 走渲染图片走解码CSS 直接注入。这个链路决定了它的能力边界凡是 chmlib 能正确解压的段chmsee 就能显示chmlib 解不动的比如某些非标准 LZX 变体或加密段界面上就是空白或报错。提示判断一个 CHM 能不能被 chmsee 打开最省事的办法是先用命令行工具extract_chmLib试抽一个文件出来抽得动基本就能读抽不动就别在 GUI 上反复试了。2.2 依赖栈与安装路径的选择chmsee 的依赖不算轻但都是发行版仓库里的常规包GTK 2.x老版本或 GTK 3较新分支、WebKitGTK 作为渲染引擎、chmlib 做容器解析、libgcrypt 处理校验。不同发行版的包名差异很大装之前先确认仓库里有没有现成包没有再从源码编。下面这套流程是我在 Debian 系上跑通的其他系把包管理器命令换掉即可。# 先查仓库里有没有现成包有就直接装别急着编译 apt-cache search chmsee # 若返回结果为空安装编译依赖Debian/Ubuntu 系 sudo apt-get install build-essential pkg-config \ libgtk-3-dev libwebkit2gtk-4.0-dev libchm-dev libgcrypt20-dev \ intltool autoconf automake libtool这段命令的逻辑是第一步只做查询避免明明有二进制包却去折腾源码第二步把编译期需要的头文件和工具一次装齐其中libchm-dev提供 chmlib 的头文件libwebkit2gtk-4.0-dev提供渲染引擎intltool和autoconf系列是 autotools 构建链的必需品。参数上没什么可调的唯一要注意的是 WebKitGTK 的版本号——4.0 和 4.1 是两套 ABI源码里configure.ac写死哪一个就得装哪一个装错了会在链接阶段报 undefined reference。源码构建的标准三步走# 在源码根目录执行先生成 configure 脚本 ./autogen.sh # 指定安装前缀装到 /usr/local 避免污染系统包 ./configure --prefix/usr/local # 并行编译核数按机器来 make -j$(nproc) sudo make install--prefix/usr/local是我习惯的做法好处是卸载时直接删目录不会和包管理器打架代价是ldconfig缓存里可能找不到新库首次运行若报error while loading shared libraries执行一次sudo ldconfig即可。make -j$(nproc)里的nproc返回逻辑核数编译 chmsee 这种规模的项目四核机器一两分钟就完事没必要开太高并行度反而抢内存。2.3 首次启动与界面元素的实际含义装完直接敲chmsee启动界面分三块左侧目录树、右侧正文区、顶部工具栏。打开文件走「文件 → 打开」或者命令行直接带路径chmsee /path/to/manual.chm。这里有个容易被忽略的点chmsee 的目录树读的是#IVB段如果某份 CHM 的制作者用了非标准的目录结构常见于用第三方工具二次打包的文档左侧可能是空的但正文仍能通过「首页」按钮或手动输入内部路径访问。工具栏上的「后退/前进」是基于内部路径的历史栈不是浏览器那种完整会话恢复「查找」只搜当前页面文本不做全书索引检索——这是它和商业阅读器最大的功能差距。如果你的诉求是「在几百页手册里全文搜关键词」chmsee 帮不上忙得换思路后面第 5 章会讲怎么用外部工具补这块。但如果只是「按目录翻、看图文混排的章节」它的渲染质量在同类里算稳的尤其是表格和代码块的排版比一些纯文本抽取工具强不少。3. 把 chmsee 用顺手打开、导航与内容抽取的实操3.1 命令行打开与批量处理图形界面点开只是入门真正提效的是命令行组合。chmsee 接受文件路径参数这意味着可以配合find做批量打开或者写进脚本按项目目录自动加载对应手册。# 找出当前项目下所有 chm 文件并逐个打开适合手册分散在多个目录的情况 find ~/docs -name *.chm -type f | while read -r f; do echo 打开: $f chmsee $f done这段脚本的关键在chmsee 是 GUI 程序不加后台符号会阻塞循环导致只有第一个文件被打开。read -r的-r参数防止反斜杠被转义路径里带空格或特殊字符时更安全。实际用的时候建议加个sleep 1避免瞬间拉起十几个窗口把桌面卡住——血泪经验第一次批量开二十份手册机器直接假死了半分钟。如果只是想快速确认某份 CHM 的元信息标题、默认页、是否有目录不必开 GUI用 chmlib 自带的工具更轻# 列出 CHM 内部所有对象路径相当于看容器里装了哪些文件 extract_chmLib manual.chm /tmp/chm_dump -l # 只抽 #SYSTEM 段看元信息十六进制可读字符混合输出 extract_chmLib manual.chm /tmp/chm_dump -s-l是 list 模式只列路径不写文件输出里能看到/xxx.html、/images/yyy.png这样的内部结构据此判断目录树是否完整-s抽的是系统段输出里夹着可读字符串能快速确认文档标题和编码声明。这两个命令在排查「为什么 chmsee 打开是空白」时特别有用——先确认容器本身能不能读再怀疑渲染层。3.2 目录树异常与编码问题的处理中文 CHM 最常见的翻车点是乱码。原因有两层一是 CHM 内部 HTML 的meta charset声明和实际字节编码不一致制作者用 GBK 存内容却声明 UTF-8或反过来二是 chmsee 的渲染引擎按声明走声明错了就整页乱码。处理办法是先抽一页出来看真实编码# 抽取单个 HTML 对象用 file 命令探测真实编码 extract_chmLib manual.chm /tmp/chm_dump /index.html file -i /tmp/chm_dump/index.htmlfile -i输出形如text/html; charsetgbk这就是真实编码。如果和页面声明不符chmsee 界面上没有强制指定编码的选项老版本的短板可行的绕法是用iconv把抽出来的整份文档转成 UTF-8 再本地打包成一份新的 CHM或者干脆放弃 CHM 形态转成 HTML 目录用浏览器读。后者更省事第 5 章会给完整脚本。目录树为空则是另一类问题多半是#IVB段结构非标准。判断方法还是extract_chmLib -l如果列出的路径里有.hhc文件HTML Help 的目录定义文件说明目录信息在只是 chmsee 没解析出来这时可以手动抽.hhc看结构或者直接用正文区的「首页」按钮逐页翻。这类文档不多但遇到一次就够折腾提前用-l探一遍能省不少时间。3.3 从阅读到抽取把 CHM 转成可检索的本地文档chmsee 的定位是「读」不是「转」。但实际工作里读完往往要引用、要搜索、要归档这时候就得把内容抽出来。chmlib 的extract_chmLib是现成的抽取器配合find和sed能把整份 CHM 摊平成普通 HTML 目录。# 把整份 CHM 抽到指定目录目录不存在会自动建 mkdir -p /tmp/manual_html extract_chmLib manual.chm /tmp/manual_html # 统计抽出的文件数和总体积确认没有中途失败 find /tmp/manual_html -type f | wc -l du -sh /tmp/manual_htmlextract_chmLib的第二个参数是输出目录第三个参数可选指定只抽某个对象不给就全抽。抽完之后目录结构基本还原了 CHM 内部的路径层级HTML 之间的相对链接大多还能用直接用浏览器打开入口页就能读。这一步的价值在于抽出来的 HTML 可以被grep、被全文索引工具扫、被版本控制管理chmsee 做不到的「全书搜索」在这里补上了。注意抽取出来的 HTML 里可能残留ms-its:这类 Windows 专有协议链接指向 CHM 内部其他对象。浏览器不认这种协议点了没反应。批量替换成相对路径即可sed -i s|ms-its:[^:]*::|/|g能处理大部分情况替换前先备份。4. 避坑清单chmsee 装不上、打不开、显示错的五类现场4.1 编译期报 WebKit 头文件找不到现象./configure阶段报Package webkit2gtk-4.0 was not found但明明装了libwebkit2gtk-4.0-dev。原因通常是pkg-config的搜索路径没包含该包的.pc文件或者装的是 4.1 版本而源码要 4.0。解决先pkg-config --list-all | grep webkit确认实际可用的包名再对照configure.ac里的PKG_CHECK_MODULES行版本对不上就装对应版本的 dev 包路径问题则export PKG_CONFIG_PATH/usr/lib/x86_64-linux-gnu/pkgconfig:$PKG_CONFIG_PATH后重跑 configure。4.2 运行时报共享库缺失现象chmsee: error while loading shared libraries: libchm.so.0: cannot open shared object file。原因是源码装到了/usr/local/lib但动态链接器缓存没更新。解决sudo ldconfig刷新缓存若仍不行检查/etc/ld.so.conf.d/下有没有包含/usr/local/lib的配置没有就补一行再ldconfig。这类问题在自定义 prefix 安装时几乎必现养成装完就跑一次ldconfig的习惯能省很多排查时间。4.3 打开 CHM 后正文区全白现象目录树正常点节点正文区一片空白。原因分两种一是该页面的 HTML 引用了外部资源如http://开头的图片或样式离线环境下加载失败导致渲染中断二是页面编码声明错误渲染引擎解析失败。解决先用extract_chmLib抽出该页file -i看编码编码对就用文本编辑器打开看有没有外链引用有的话批量替换成本地相对路径或直接删掉引用标签。判断顺序永远是「先容器后渲染」别一上来就怀疑 chmsee 本身。4.4 中文显示成方块或问号现象正文能渲染但中文全是方块。原因是系统缺中文字体WebKitGTK 找不到可用字形就画方块。解决装一套中文字体如fonts-noto-cjk然后fc-cache -fv刷新字体缓存。这个坑和 chmsee 无关任何基于 WebKit 的阅读器在精简系统上都会遇到装完字体重启程序即可。顺带一提字体装全了之后代码块里的等宽字体渲染也会更正常算是一举两得。4.5 大文件打开卡顿甚至无响应现象打开几十 MB 的 CHM 时界面卡住进度条不动。原因是 chmsee 在构建目录树时同步读取#IVB大文档的目录节点多主线程被占满。解决先用extract_chmLib -l确认文件规模节点数上千的话别指望 GUI 流畅直接走抽取路线用浏览器读如果非要 GUI启动后耐心等目录树加载完再操作中途点击会加剧卡顿。这类性能问题没有配置项可调属于工具设计上的边界认清它比硬扛更实际。5. 进阶用抽取脚本把 CHM 变成可全文检索的本地知识库chmsee 读单份文档够用但当你手上有十几份 CHM 手册、需要跨文档搜一个 API 名或错误码时GUI 逐个翻就太慢了。我的做法是用extract_chmLib批量摊平再用一个轻量索引脚本把 HTML 转成纯文本并建倒排索引最后用grep -r或ripgrep直接搜。整套流程不需要额外服务纯命令行适合放在项目目录里随用随跑。先写批量抽取脚本处理多份 CHM 并统一输出结构#!/usr/bin/env bash # batch_extract.sh把指定目录下所有 CHM 抽到独立子目录 set -euo pipefail SRC_DIR${1:?用法: $0 chm目录 输出目录} OUT_DIR${2:?用法: $0 chm目录 输出目录} mkdir -p $OUT_DIR find $SRC_DIR -name *.chm -type f | while read -r chm; do # 用文件名去扩展名作为子目录名避免不同手册互相覆盖 base$(basename $chm .chm) target$OUT_DIR/$base mkdir -p $target echo 抽取 $chm - $target # 单份失败不中断整体流程 extract_chmLib $chm $target || echo 警告: $chm 抽取失败跳过 doneset -euo pipefail让脚本在管道任一环节出错时立即退出避免半途而废留下脏数据${1:?...}是参数校验缺参数直接报用法而不是静默跑错目录。|| echo那行是刻意放宽的单份 CHM 损坏不应该拖垮整批任务记录警告继续跑更符合实际。输出目录按文件名分子目录是因为不同手册内部路径经常重名都有/index.html混在一起会互相覆盖。抽取完的 HTML 里混着标签直接grep会命中大量无关的 class 名和脚本。加一步转纯文本# 用 python 标准库做 HTML 转文本不引入第三方依赖 python3 - PY import pathlib, re, html root pathlib.Path(/tmp/manual_html) for p in root.rglob(*.htm*): raw p.read_text(encodingutf-8, errorsignore) # 去掉 script/style 块再去标签最后反转义实体 raw re.sub(r(script|style)[^]*.*?/\1, , raw, flagsre.S|re.I) text re.sub(r[^], , raw) text html.unescape(text) text re.sub(r\s, , text).strip() p.with_suffix(.txt).write_text(text, encodingutf-8) print(转换完成) PY这段 Python 的逻辑是三步清洗先整块删掉script和style这两类内容对检索毫无价值还特别占体积再用正则把剩余标签替换成空格不是删掉避免相邻单词粘连最后html.unescape把amp;这类实体还原成字符\s压缩连续空白。errorsignore是兜底前面编码问题没处理干净的页面不至于让脚本崩掉。转出来的.txt和原 HTML 同目录用rg搜的时候加-g *.txt限定范围即可。实际检索时我一般这样用# 在所有转出的文本里搜关键词显示文件名和行号 rg -n -g *.txt 错误码 E1024 /tmp/manual_html # 只统计哪些手册命中快速定位该翻哪一份 rg -l -g *.txt E1024 /tmp/manual_html | xargs -n1 dirname | sort -u-l只输出命中文件名配合xargs dirname和sort -u就能得到「哪几份手册提到过这个错误码」的清单比逐个打开 chmsee 翻目录快一个数量级。这套组合的边界也很清楚它做的是字面匹配不理解语义同义词和拼写变体搜不到但对技术手册这种术语固定的材料字面检索的命中率已经足够高。从那以后我每次拿到一批 CHM都强制先跑一遍extract_chmLib -l探容器、再批量抽取转文本确认索引建好之后才决定要不要开 GUI 精读——这个顺序帮我避开了好几次「打开是空白还以为文件坏了」的乌龙。希望帮到你。本文还有配套的精品资源点击获取
