企业官网建设流程全解析

简介：面向 Linux 桌面用户与开发者的一份 CHM 阅读工具源码包，用于解决 Linux 环境下无法直接打开微软编译的 HTML 帮助文档这一常见困扰。chmsee 对中文 CHM 文档支持良好，可解析并显示目录、索引与正文，还提供全文搜索、书签管理、右键导航菜单等实用功能，界面简洁，适合经常查阅技术手册、离线文档的学习者与运维人员。压缩包共 111 个文件，约 355KB，以 C 与 C++ 源文件、头文件、automake 构建脚本（am、m4、ac）、configure 配置脚本为主，另含 glade 界面描述、po 与 pot 多语言翻译、desktop 与 mime 桌面集成文件、gif 与 png 图标资源及 readme、changelog 等说明文档，构成一套可编译的完整工程。已有 468 人学习下载，读者可据此了解 CHM 解析实现、Firefox 插件集成方式与依赖库配置思路，并自行编译安装使用。

1. 从一次打不开的离线手册说起：chmsee 在 Linux 上到底装什么

上周帮某实验室的同事恢复一台旧开发机，桌面环境是轻量级的 Xfce，系统里躺着一份几百兆的 CHM 格式离线手册，双击之后弹出来的却是一个空窗口，标题栏写着 chmsee，正文一片白。这种场景在 Linux 桌面里太常见了：CHM 是 Windows 时代留下的帮助文档格式，Linux 原生并不认它，得靠专门的阅读器来解包渲染。chmsee 就是这类工具里比较老牌的一个，基于 GTK 和 xulrunner 那一套技术栈，界面朴素，胜在能直接索引 CHM 内部的目录树和全文搜索。装不好会怎样？轻则白屏、乱码，重则一启动就段错误退出，连报错都看不到。这篇笔记面向的是手里有 CHM 资料、想在 Linux 桌面上把它正常翻开的开发者，从版本选择一路写到装完怎么验证，中间踩过的坑一并记下来。

2. 装前把环境列清：chmsee 的依赖与版本取舍

chmsee 不是一个能靠一条apt install就万事大吉的软件，它的麻烦在于年代久远，依赖链里混着 GTK2、xulrunner 和一堆 C++ 运行时库。动手之前先把环境摸清楚，比装到一半再回头补依赖省事得多。这一章先把「装什么版本、依赖哪些包、系统怎么选」讲透，后面几章才好落地。

2.1 先确认发行版和桌面栈

chmsee 的活跃年代大致对应 GTK2 时代，所以它对桌面环境是有偏好的。GNOME 2、Xfce、MATE 这类还保留 GTK2 运行时的环境最省心；纯 GTK3/GTK4 的现代桌面（比如某些精简版 GNOME）虽然也能跑，但需要额外把 GTK2 的兼容库补齐。先跑两条命令看清楚底子：

# 看发行版和版本号，决定后面用 apt 还是 dnf cat /etc/os-release # 看当前桌面是否还带 GTK2 运行时 pkg-config --modversion gtk+-2.0 2>/dev/null || echo "GTK2 开发库未安装"

第一条命令输出里的ID和VERSION_ID决定了包管理器是apt还是dnf，也决定了软件源里还能不能找到 chmsee 的现成包。第二条命令如果直接打印出版本号（常见是 2.24.x），说明 GTK2 开发库在；如果走到echo分支，说明得先补libgtk2.0-dev这类包。我一般会先看这两条再决定路线，避免在 GTK3-only 的系统上硬编译，最后卡在一堆找不到的头文件上。

2.2 依赖清单与版本对照

chmsee 的核心依赖可以分成三类：GTK2 图形库、CHM 解析库（chmlib）、以及它自带的 xulrunner 渲染引擎。不同发行版打包时对这几样的版本要求略有差异，下面这张表是我在几类常见系统上整理出来的对照，装之前照着核一遍：

这里要特别说一句 xulrunner。它是 chmsee 渲染正文的关键，但很多新发行版已经把它从主源里移除了，只留一个残缺的兼容包。常见做法是优先用发行版自带的 chmsee 二进制包（如果源里还有），它会自动把 xulrunner 的依赖关系带进来；只有当源里彻底没有时，才考虑自己编译，而自己编译时 xulrunner 的版本必须和 chmsee 源码里写死的接口对得上，差一个大版本就可能链接失败。

2.3 两条安装路线怎么选

路线一：包管理器直接装。适合 Debian/Ubuntu 的老版本、以及还维护 chmsee 包的衍生发行版。优点是依赖自动解决，缺点是版本可能偏旧。

路线二：源码编译。适合源里已经没有 chmsee、或者需要打补丁修复白屏问题的场景。优点是可控，缺点是依赖要自己一个个补齐。

我一般的判断标准是：先apt-cache search chmsee或dnf search chmsee探一下，有包就走路线一，没有再看源码。下面两章分别把这两条路线写清楚，读者按自己系统的情况挑一条走即可。

3. 包管理器安装：从探源到首次启动

这一章走路线一，把「探源、装包、补依赖、首次启动」串成一条能照着敲的流程。包管理器安装看起来简单，但 chmsee 这种老软件在新系统上经常出现「包装上了、依赖却缺一块」的情况，所以每一步后面都跟一句怎么确认。

3.1 探源与安装命令

先确认源里到底有没有这个包，别急着敲 install：

# Debian/Ubuntu 系：搜索包名，确认是否存在 apt-cache search chmsee # RHEL/Fedora 系：同样先搜 dnf search chmsee

如果搜索有结果，说明源里有现成的包，直接装：

# Debian/Ubuntu 系安装，-y 表示自动确认 sudo apt install -y chmsee # RHEL/Fedora 系安装 sudo dnf install -y chmsee

apt-cache search只查不装，用来判断路线；install -y里的-y是跳过交互确认，适合脚本化操作，手动装时去掉也无妨。装完先别急着打开 CHM，跑一下版本查询确认二进制真的落地了：

# 确认可执行文件位置和是否能正常加载动态库 which chmsee ldd $(which chmsee) | grep "not found"

ldd那条是关键：如果输出里有not found，说明有动态库没被依赖关系带进来，这时候别硬启动，先把缺的库补上，否则一启动就是段错误。这一步是我踩过坑之后养成的习惯，能提前把「装上了但跑不起来」的问题拦在启动之前。

3.2 缺依赖时的补齐顺序

ldd报缺库时，补齐是有顺序的：先补 GTK2 运行时，再补 chmlib，最后处理 xulrunner。原因是前两个是硬依赖，缺了直接起不来；xulrunner 缺了往往表现为能启动但正文白屏，属于「半残」状态。

# 补 GTK2 运行时和 chmlib 运行时（Debian 系） sudo apt install -y libgtk2.0-0 libchm1 # 补开发库（如果后面要编译或打补丁） sudo apt install -y libgtk2.0-dev libchm-dev

libgtk2.0-0是运行时库，libgtk2.0-dev是开发头文件，只跑不编译的话装前者就够。libchm1同理。补完之后再跑一次ldd，确认not found消失。如果缺的是 xulrunner 相关的库，先看发行版有没有xulrunner或libxul的兼容包，有就装，没有就记下来，留到第 5 章的排查里处理。

3.3 首次启动与基础配置

装好依赖后第一次启动，建议从终端里跑，这样报错能直接看到：

# 从终端启动，保留标准错误输出 chmsee /path/to/manual.chm

把/path/to/manual.chm换成你实际的 CHM 文件路径。从终端启动的好处是，如果程序崩溃，终端里会打印出类似Segmentation fault或 GTK 的警告，这些信息比图形界面里一个空窗口有用得多。首次启动后如果界面正常、目录树能展开，说明基础环境通了；如果白屏，先别怀疑安装，多半是 xulrunner 渲染层的问题，翻到第 5 章对照排查。

基础配置方面，chmsee 的设置项不多，主要在「视图」里调字体和编码。中文 CHM 常见乱码，原因是文档内部编码和程序默认编码不一致，在设置里把编码手动指定为 GBK 或 GB18030 往往能解决。这个配置不写进配置文件也行，每次打开时在菜单里选一次即可，属于「知道在哪调」比「提前配好」更实用的项。

4. 源码编译：configure 参数与编译排错

源里没有 chmsee 的时候就得自己编译。这条路线的难点不在敲命令，而在 configure 阶段的各种「找不到」，以及编译时老代码对新编译器的兼容问题。这一章按「取源码、配参数、编译、装」的顺序走，每一步都写清楚失败时看哪里。

4.1 取源码与目录准备

源码一般是一个 tar 包，解压后进目录。这里不写具体下载地址，按你手里拿到的包名操作即可：

# 解压源码包，x 解包、z 处理 gzip、f 指定文件 tar -xzf chmsee-*.tar.gz # 进入解压出来的目录 cd chmsee-*/

解压后先别急着 configure，扫一眼目录里有没有README和INSTALL，老项目的这两个文件里经常写着它期望的 xulrunner 版本和额外的编译开关，比盲目试参数高效。我一般会先ls看一眼有没有configure脚本，没有的话说明得先跑autogen.sh生成。

4.2 configure 的关键参数

configure 阶段最容易卡在「找不到某个库」。下面这组参数是我在多数环境下会用的起步配置：

# 指定安装前缀，关闭不需要的调试符号，显式给出 chmlib 路径 ./configure \ --prefix=/usr/local \ --disable-debug \ --with-chmlib-prefix=/usr

--prefix=/usr/local把安装目录定在/usr/local，避免污染系统自带的/usr；--disable-debug关掉调试符号，减小体积、加快编译；--with-chmlib-prefix=/usr告诉 configure 去哪里找 chmlib 的头文件和库，如果 chmlib 装在别处，把路径改成实际位置。configure 跑完会打印一份摘要，重点看xulrunner那一行是不是yes，如果是no，说明渲染引擎没找到，后面编译出来的程序大概率白屏。

如果 configure 报Package gtk+-2.0 was not found，说明 pkg-config 找不到 GTK2 的.pc文件，常见做法是确认libgtk2.0-dev已装，并用export PKG_CONFIG_PATH=/usr/lib/pkgconfig把路径补进环境变量再重跑。

4.3 编译与安装

configure 通过后就可以编译了。老代码在新 GCC 上编译，最常见的报错是头文件缺失和 C++ 标准不兼容：

# 并行编译，-j 后面的数字按 CPU 核心数填，这里用 4 make -j4 # 编译成功后安装到 configure 指定的前缀 sudo make install

make -j4里的-j是并行任务数，填多了内存吃紧反而慢，填少了浪费核心，一般按nproc的结果来。如果编译中途报fatal error: xxx.h: No such file or directory，先确认对应的-dev包装了没有；如果报的是 C++ 语法相关的错误（老代码用了一些新标准里被移除的写法），常见做法是在CXXFLAGS里加-std=c++98或-fpermissive让编译器宽容一些：

# 用兼容模式重新编译，适合老代码遇到新编译器报语法错 make clean make CXXFLAGS="-std=c++98 -fpermissive" -j4

make clean先清掉上一次的中间产物，避免新旧目标文件混在一起；CXXFLAGS覆盖默认的 C++ 编译选项，-std=c++98让编译器按老标准解析，-fpermissive把一些原本是错误的地方降级为警告。这两个参数是权宜之计，能编过就行，不必追求零警告。装完之后同样用ldd确认一遍动态库，再按第 3.3 节的方式从终端启动验证。

5. 避坑与排查：chmsee 装完跑不起来的五种情况

chmsee 的坑集中在「装完」和「跑起来」之间那一段，界面出不来、正文白屏、中文乱码，每一种背后原因都不一样。这一章按「现象 → 原因 → 解决」记五条我实际遇到过的，照着对号入座能省不少时间。

5.1 启动即段错误，终端只打印 Segmentation fault

现象：命令行敲chmsee回车，没有任何窗口，终端直接输出Segmentation fault (core dumped)。

原因：绝大多数是动态库版本不匹配，尤其是 xulrunner 的 ABI 和 chmsee 编译时链接的版本对不上，程序在初始化渲染引擎时访问了非法地址。

解决：先用ldd $(which chmsee)看有没有not found，有就补库；没有的话，用gdb chmsee跑一次，看崩溃栈顶落在哪个库上。如果落在libxul相关符号，说明 xulrunner 版本不对，换一个和源码匹配的版本重装，或者退回包管理器安装的二进制版本。

5.2 窗口能开，正文一片白

现象：程序正常启动，左侧目录树也在，点章节标题右侧正文区全白。

原因：渲染层没工作。chmsee 把 CHM 里的 HTML 抽出来交给 xulrunner 渲染，xulrunner 缺失或初始化失败时，界面框架还在，内容区就是空的。

解决：确认 configure 摘要里 xulrunner 是yes；如果是包管理器装的，检查libxul兼容包是否装上。实在找不到匹配的 xulrunner，可以退而求其次，用 chmlib 自带的解包工具把 CHM 拆成 HTML 再用浏览器看，虽然丢了目录联动，但内容能读。

5.3 中文显示成方块或乱码

现象：正文能显示，但中文全是方块，或者是一堆问号和乱码字符。

原因：编码不匹配。CHM 内部可能是 GBK/GB18030 编码，程序按 UTF-8 去解，自然对不上；方块则是系统缺中文字体。

解决：先在 chmsee 的视图菜单里手动把编码切成 GB18030 试一次；如果还是方块，装一套中文字体（如fonts-wqy-zenhei），再用fc-cache -fv刷新字体缓存。这两步做完基本能正常显示。

5.4 configure 报找不到 gtk+-2.0

现象：源码编译时./configure中途退出，提示Package gtk+-2.0 was not found in the pkg-config search path。

原因：GTK2 开发库没装，或者装了但.pc文件不在 pkg-config 的默认搜索路径里。

解决：先sudo apt install libgtk2.0-dev，再pkg-config --modversion gtk+-2.0确认能查到版本。查不到就手动指定路径：export PKG_CONFIG_PATH=/usr/lib/x86_64-linux-gnu/pkgconfig:$PKG_CONFIG_PATH，然后重跑 configure。路径里的架构目录按实际系统调整。

5.5 装完命令找不到

现象：make install显示成功，但敲chmsee提示command not found。

原因：安装前缀是/usr/local，而/usr/local/bin不在当前 shell 的PATH里，或者没跑ldconfig导致动态库缓存没更新。

解决：先echo $PATH看有没有/usr/local/bin，没有就export PATH=/usr/local/bin:$PATH并写进 shell 配置文件；再sudo ldconfig刷新动态库缓存。两步做完再试一次，通常就正常了。

6. 装完怎么验证：三步确认 chmsee 真的能用

装完不等于能用，尤其 chmsee 这种依赖链长的老工具，得有一套固定的验证动作。我一般分三步走：先验二进制和动态库，再验 CHM 解析，最后验渲染和中文显示。三步都过，才算这套环境真的落地。

第一步，验二进制和动态库。这一步在装完当下就做，别等打开文件才发现问题：

# 确认可执行文件存在，且所有动态库都能解析 which chmsee ldd $(which chmsee) | grep -c "not found"

第二条命令的grep -c统计not found出现的次数，输出0才算干净。只要不是 0，就回到第 5.1 节按缺库处理，别往下走。

第二步，验 CHM 解析。拿一个结构完整的 CHM 文件，从终端启动并观察目录树：

# 从终端启动，同时把标准错误重定向到文件，方便事后看 chmsee /path/to/manual.chm 2> /tmp/chmsee_err.log

启动后看左侧目录树能不能完整展开、点章节标题右侧有没有内容。如果目录树正常但正文白屏，翻第 5.2 节；如果连目录树都出不来，看/tmp/chmsee_err.log里的报错，多半是 CHM 文件本身损坏或 chmlib 版本太老解析不了。

第三步，验渲染和中文。打开一个含中文的章节，确认字体不是方块、编码不是乱码。这一步没有命令可跑，靠肉眼，但可以配合字体检查：

# 确认系统里至少有一套中文字体可用 fc-list :lang=zh | head -n 3

fc-list :lang=zh列出所有支持中文的字体，head -n 3只看前三条，有输出说明字体在。如果前面显示正常但这里查不到中文字体，说明是程序内置了字体回退，换个 CHM 文件可能就露馅，建议还是把中文字体装上。

三步验证下来，我习惯把结果记一笔：二进制路径、ldd是否干净、测试用的 CHM 文件名、中文是否正常。这套记录在换机器或重装系统时特别有用，照着复现一遍就知道环境有没有退化。从那以后我每次装这类老工具，都强制走一遍「ldd 干净、目录树能开、中文不乱」这三关，少一关都不算装完。希望帮到你。

本文还有配套的精品资源，点击获取