XTerminal 反馈社区

YueZZ

Ubuntu 20.04.6 LTS 有 XTerminal GLIBC。
新建ssh的时候会有报错。

XTerminal GLIBC 兼容性修复文档
问题描述
在 Ubuntu 20.04（GLIBC 2.31）上运行 XTerminal 5.6.0 时，出现以下错误：

/lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.33' not found
(required by /opt/XTerminal/resources/app.asar.unpacked/node_modules/better-sqlite3/build/Release/better_sqlite3.node)
根因：XTerminal 自带的 better_sqlite3.node 预编译二进制文件是在 GLIBC 2.33+ 的系统上编译的，与 Ubuntu 20.04 的 GLIBC 2.31 不兼容。

环境信息
项目版本
操作系统 Ubuntu 20.04 (Linux 5.15.0-139-generic)
GLIBC 2.31
XTerminal 5.6.0
Electron 40.6.0 (Chrome 144, Node ABI 143)
better-sqlite3 12.6.2
系统 Node.js v18.20.8 (nvm)
修复方案：本地重新编译 better-sqlite3
由于预编译的二进制文件不兼容，在本地使用 g++-11 重新编译 better_sqlite3.node，使其链接到本地 GLIBC 2.31。

操作步骤

安装 g++-11 编译器
better-sqlite3 12.6.2 + Electron 40 的 V8 头文件需要完整的 C++20 支持（包括 <compare> 和 <source_location> 头文件），至少需要 GCC 11。

为什么不能用 GCC 9 或 GCC 10？

GCC 9：不支持 -std=c++20 标志（只有 -std=c++2a），且缺少 <compare> 头文件
GCC 10：支持 -std=c++20，有 <compare>，但缺少 <source_location> 头文件
GCC 11+：完整支持 C++20 所有特性
Ubuntu 20.04 默认仓库不含 g++-11，需要从 Ubuntu Toolchain PPA 安装：

步骤 1：添加 PPA（需要网络访问 Launchpad）

sudo add-apt-repository -y ppa:ubuntu-toolchain-r/test

步骤 2：更新包列表

sudo apt-get update

步骤 3：安装 g++-11

sudo apt-get install -y g++-11
注意：如果 add-apt-repository 命令卡住（常见于公司内网环境，因为无法访问 ppa.launchpad.net），可以 Ctrl+C 取消后直接尝试 sudo apt-get install -y g++-11。原因：add-apt-repository 在超时前可能已经将 PPA 源写入了 /etc/apt/sources.list.d/ 并部分更新了包列表。

如果仍然找不到包，可以手动添加源：

echo "deb http://ppa.launchpad.net/ubuntu-toolchain-r/test/ubuntu focal main" | sudo tee /etc/apt/sources.list.d/ubuntu-toolchain-r-test.list
sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 1E9377A2BA9EF27F
sudo apt-get update
sudo apt-get install -y g++-11
验证安装：

g++-11 --version

输出: g++-11 (Ubuntu 11.5.0-...) 11.5.0

创建临时编译目录
mkdir -p /tmp/rebuild-better-sqlite3
cd /tmp/rebuild-better-sqlite3
npm init -y
安装 better-sqlite3 源码
cd /tmp/rebuild-better-sqlite3
npm install better-sqlite3@12.6.2 --registry=https://registry.npmmirror.com
注意：这一步使用系统 Node.js 编译，会有 engine 版本警告，可以忽略。
为 Electron 40.6.0 重新编译
关键步骤：使用 node-gyp 指定 Electron 的头文件来编译，确保 ABI 匹配。

cd /tmp/rebuild-better-sqlite3/node_modules/better-sqlite3

CXX=g++-11 CC=gcc-11 npx node-gyp rebuild
--release
--target=40.6.0
--arch=x64
--dist-url=https://electronjs.org/headers
编译参数说明：

CXX=g++-11 CC=gcc-11：指定使用 GCC 11 编译器
--target=40.6.0：指定 Electron 版本，用于下载对应的 Node.js 头文件
--arch=x64：目标架构
--dist-url=https://electronjs.org/headers：Electron 头文件下载地址
编译成功标志：输出末尾显示 gyp info ok。

验证编译产物
检查新编译的文件不依赖高版本 GLIBC：

objdump -T /tmp/rebuild-better-sqlite3/node_modules/better-sqlite3/build/Release/better_sqlite3.node
| grep GLIBC | awk '{print $5}' | sort -u
预期结果：最高 GLIBC 版本应 <= 2.31（实测最高为 GLIBC_2.29）。

备份并替换原文件

备份原文件

sudo cp /opt/XTerminal/resources/app.asar.unpacked/node_modules/better-sqlite3/build/Release/better_sqlite3.node
/opt/XTerminal/resources/app.asar.unpacked/node_modules/better-sqlite3/build/Release/better_sqlite3.node.bak

替换为新编译的文件

sudo cp /tmp/rebuild-better-sqlite3/node_modules/better-sqlite3/build/Release/better_sqlite3.node
/opt/XTerminal/resources/app.asar.unpacked/node_modules/better-sqlite3/build/Release/better_sqlite3.node
7. 重启 XTerminal
killall xterminal
sleep 1
/opt/XTerminal/xterminal &
GLIBC 依赖对比
原始文件重新编译后
GLIBC 最高版本 2.34 2.29
GLIBCXX 最高版本 3.4.29 3.4.29
文件大小 2,140,552 bytes 2,143,536 bytes
回退方法
如果替换后出现问题，可以恢复原始文件：

sudo cp /opt/XTerminal/resources/app.asar.unpacked/node_modules/better-sqlite3/build/Release/better_sqlite3.node.bak
/opt/XTerminal/resources/app.asar.unpacked/node_modules/better-sqlite3/build/Release/better_sqlite3.node
注意事项
XTerminal 更新后需重复操作：XTerminal 更新时会覆盖 better_sqlite3.node，需要重新执行步骤 3-7。更新后 Electron 版本和 better-sqlite3 版本可能会变，需要重新获取：

获取新的 Electron 版本

ELECTRON_RUN_AS_NODE=1 /opt/XTerminal/xterminal -e "console.log('Electron:', process.versions.electron)"

获取新的 better-sqlite3 版本

前提：已全局安装 asar 工具（npm install -g @electron/asar）

ASAR_PATH=$(npm root -g)/@electron/asar
node -e "const asar = require('$ASAR_PATH'); const buf = asar.extractFile('/opt/XTerminal/resources/app.asar', 'node_modules/better-sqlite3/package.json'); console.log('better-sqlite3:', JSON.parse(buf).version);"
获取到的版本号对应使用位置：
Electron 版本（如 40.6.0）→ 用于步骤 4 的 --target=40.6.0 参数，指定编译目标的 Node ABI
better-sqlite3 版本（如 12.6.2）→ 用于步骤 3 的 npm install better-sqlite3@12.6.2，安装匹配的源码
GCC 版本要求：
GCC 9：不支持 -std=c++20 标志
GCC 10：缺少 <source_location> 头文件
GCC 11+：满足所有 C++20 要求
编译缓存：Electron 头文件缓存在 ~/.cache/node-gyp/40.6.0/，首次编译需下载
备份文件位置：/opt/XTerminal/resources/app.asar.unpacked/node_modules/better-sqlite3/build/Release/better_sqlite3.node.bak
其他可选方案（未采用）
方案优缺点
升级到 Ubuntu 22.04+ 彻底解决，但需要全面升级系统
降级 better-sqlite3 可能与 XTerminal 不兼容
Docker 容器运行过于重量级
升级 GLIBC 风险极高，可能导致系统不稳定
文档生成日期：2026-04-07 操作环境：Ubuntu 20.04 LTS, XTerminal 5.6.0, Electron 40.6.0