MarkText Linux 开发环境搭建指南前置依赖、构建准备与常见报错排查【免费下载链接】marktextA simple and elegant markdown editor, available for Linux, macOS and Windows.项目地址: https://gitcode.com/gh_mirrors/ma/marktext本篇指南围绕 MarkText 官方开发文档《Linux Specific Pre-requisites》packages/website/content/docs/dev/LINUX_DEV.md展开完整讲解在 Ubuntu / Fedora 等 Linux 发行版上从零搭建 MarkText 桌面端Electron 应用开发与构建环境所需的系统级前置依赖、Node.js 工具链配置以及pnpm install阶段最常遇到的三个报错native-keymap 编译失败、Electron 缺少 libglib、pnpm store 权限问题的根因与修复方法。读完本文你将能够在 Linux 上顺利跑通依赖安装并进入pnpm run dev/pnpm run build:linux的正常开发构建流程。为什么 Linux 构建需要额外的系统依赖MarkText 桌面端是典型的 Electron Vue 应用核心源码位于 packages/desktopElectron 主进程、preload 与渲染进程与 packages/muya编辑器内核。pnpm install并不仅仅是拉取 JavaScript 依赖——安装过程中还会触发native 模块的源码编译这正是 Linux 平台需要额外系统依赖的根本原因。其中最具代表性的 native 模块是native-keymap它被声明在 packages/desktop/package.json 的optionalDependencies中native-keymap: ^3.3.9它在运行时用于读取操作系统当前键盘布局与按键映射。在 packages/desktop/src/main/keyboard/index.ts 中主进程直接通过getCurrentKeyboardLayout()、getKeyMap()与onDidChangeKeyboardLayout()三个 API 获取键盘信息进而为 MarkText 的快捷键系统提供跨语言、跨布局的按键判定依据它是 C/C 扩展在 Linux 上编译时需要pkg-config找到X11 与 XKBfile开发库。从仓库自带的补丁 packages/desktop/patches/native-keymap3.3.9.patch 可以看到其binding.gyp在 Linux 分支下通过pkg-config x11 xkbfile --libs完成链接。因此一旦系统缺少 X11 相关开发头文件编译必然失败。此外native-keymap之所以被放入optionalDependencies是因为在较新的 Node 版本如 Node v24下其自带的 node-gyp 编译常常失败pnpm 会将其降级为可选依赖失败而继续安装。仓库根目录的 scripts/postinstall.ts 中明确注释了这一策略postinstall 阶段会恢复 native-keymap 源码、应用 C20 补丁再通过electron/rebuild针对 Electron 的 ABI 重新编译并顺带完成 Electron 二进制下载与 locale 文件生成。这也解释了为什么 Linux 上的xorg-dev缺一不可——它是这条 native 编译链的底层支撑。系统需求与版本约束根据原文档Linux 上构建 MarkText 的最低资源要求如下项目要求说明磁盘空间约 1.2 GB仅满足基础构建含 Electron 二进制与依赖缓存内存建议 ≥ 4 GBElectron 构建与打包阶段内存占用明显这些数字是针对基础构建的实测值文档注明已在Ubuntu 24.04.2 LTS与Ubuntu 22.04 LTS上验证后者由贡献者 FP Coetzee 提供验证结果。若同时运行开发服务器、Playwright 测试或打包多发行版产物建议预留更多资源。除了资源还有一条与 Linux 开发密切相关的工具链版本约束来自仓库根目录 package.json 的engines字段Node.js20.19.0pnpm10仓库通过packageManager锁定pnpm10.33.4并建议配合corepack使用同时packages/website/content/docs/dev/README.md 指出编译 native 模块还需要Python3.12供 node-gyp 使用并提醒Node 版本不宜显著高于 Electron 内置的 Node 版本否则可能导致 native add-on 编译出现兼容性问题。第一步安装系统包Ubuntu / Debian 系执行sudo apt update sudo apt install -y git build-essential xorg-dev其中git克隆仓库与贡献流程必需build-essential提供 gcc/g 与 make是 node-gyp 编译 native 模块如 native-keymap、keytar的基础工具链xorg-dev提供 X11 开发头文件与库对应上文pkg-config x11 xkbfile --libs的链接需求是 Linux 下 native-keymap 能否编译成功的关键包。Fedora / RHEL 系sudo dnf install -y xorg-x11-server-devel libxkbfile-develRed Hat 系使用-devel后缀的包来提供开发头文件与 Ubuntu 的-dev包一一对应。更完整的依赖清单原文档只给出了最小依赖集。若你希望构建更完整的发行产物deb/rpm/snap/AppImage可以参照同目录下的 packages/website/content/docs/dev/BUILD.md 补充Debian 系sudo apt-get install libx11-dev libxkbfile-dev libsecret-1-dev libfontconfig-dev rpmRed Hat 系sudo dnf install libX11-devel libxkbfile-devel libsecret-devel fontconfig-develArch 系sudo pacman -S libx11 libxkbfile libsecret fontconfig其中libsecret与 MarkText 的keytar依赖系统密钥环集成同样出现在 pnpm-workspace.yaml 的allowBuilds白名单中相关rpm则是 Debian 系统上交叉构建 rpm 包时所需。第二步安装 Node.js 与 pnpm原文档推荐使用nvmNode Version Manager安装 Node.js以方便在多个 Node 版本间切换例如跟随仓库 CI 使用 Node 22/24或在出问题时回退版本。安装完 nvm 后nvm install 20 nvm use 20随后启用 pnpm。仓库根 package.json 的packageManager字段指定了pnpm10.33.4使用 Corepack 即可按锁定的版本安装corepack enable corepack prepare pnpm10.33.4 --activate注意BUILD.md 中推荐的容器化构建路径podman run -it -v ./:/mnt:Z node:22-bookworm /bin/bash同样适用容器内需额外从 bookworm-backports 安装 Python 3.12。第三步克隆仓库并安装依赖git clone https://github.com/marktext/marktext.git cd marktext pnpm install在 Linux 上pnpm install结束前会自动执行根目录postinstall脚本见 scripts/postinstall.ts它依次完成恢复 native-keymap 源码若 pnpm 因 optional 依赖编译失败而移除了源码目录会通过pnpm --filter marktext add native-keymap --ignore-scripts重新拉取跳过编译下载 Electron 二进制调用electron/install.js失败时自动回退到ELECTRON_MIRROR镜像默认https://npmmirror.com/mirrors/electron/应用 C20 补丁在packages/desktop目录下运行 patch-package应用 packages/desktop/patches/native-keymap3.3.9.patch该补丁为 native-keymap 增加-stdc20编译选项以适配新版 Node/Electron 工具链重建 native 模块运行electron-rebuild -f将 native-keymap、keytar 等模块按 Electron 的 ABI 重新编译这也是pnpm-workspace.yaml中allowBuilds列出native-keymap、keytar、ced等包的原因——pnpm 10 默认会拦截依赖安装脚本白名单显式放行这些确有构建需求的包生成压缩版 locale 文件执行minify-locales。依赖安装成功后即可进入开发模式pnpm run dev或进行 Linux 生产构建pnpm run build:linux构建产物由 packages/desktop/electron-builder.yml 的linux.target定义覆盖AppImage、snap、deb、rpm与tar.gz五种格式输出到仓库根目录的dist/下。常见问题排查Issue 1pnpm install 报 native-keymap 编译失败典型报错ERR_PNPM_OPTIONAL_DEPS_REQUIRER optional dep native-keymap failed ... node-gyp ERR! build error node-gyp ERR! gyp ERR! rebuild原因系统缺少xorg-dev导致 native-keymap 的 gyp 构建无法找到 X11/XKBfile 头文件与库pkg-config x11 xkbfile --libs返回空或失败最终 node-gyp 整体编译失败。由于 native-keymap 属于 optional 依赖pnpm 会以 optional dep failed 的形式继续安装流程导致后续应用补丁与重建步骤无法正确完成。解决sudo apt install xorg-dev然后重新执行pnpm install安装完成后可通过pkg-config --modversion x11 xkbfile验证库是否可见。Issue 2Electron 启动报 libglib 缺失典型报错~/marktext/node_modules/electron/dist/electron: error while loading shared libraries: libglib-2.0.so.0: cannot open shared object file: No such file or directory原因Electron 自带二进制是动态链接的运行时需要 GLib 等 X11/GUI 基础运行库。无桌面环境的最小化系统如精简容器或服务器常常缺少这些运行时库——注意这与编译期缺头文件是两类问题。解决安装 X11/GUI 开发库sudo apt install xorg-dev若问题依旧说明系统缺少完整的 X11 运行时环境可安装完整 X11 包sudo apt install xorg安装后建议重新执行pnpm install或pnpm rebuild确保 Electron 二进制与依赖完整。Issue 3pnpm install 过程出现权限错误原因使用sudo运行pnpm命令。pnpm 将包存储在全局的 content-addressable store 中Linux 默认位于~/.local/share/pnpm/store。一旦以 root 执行过 pnpmstore 目录及其缓存文件的属主就变成了 root之后以普通用户身份安装时便会出现权限拒绝。解决正确做法始终以普通用户运行 pnpm不要加sudo修复已损坏的 store将 store 目录属主改回当前用户# 检查并修复 store 属主如有必要 sudo chown -R $(whoami) ~/.local/share/pnpm修复后重新执行pnpm install即可。验证环境是否就绪依赖安装成功后可依次做三个快速验证验证 native 模块确认node_modules下 native-keymap 目录存在且electron-rebuild已完成日志中应出现 Rebuilding native modules for Electron... 且无 error验证 Electron 可执行packages/desktop/node_modules/electron/dist/electron --version能正常输出版本号而不是报libglib-2.0.so.0之类的加载错误验证开发模式执行pnpm run dev应能弹出 MarkText 主窗口。若在窗口内修改快捷键绑定相关代码可留意 packages/desktop/src/main/keyboard/index.ts 中getKeyboardInfo是否正确返回键盘布局信息——这是 native-keymap 编译成功与否的直接证据。小结Linux 上搭建 MarkText 开发环境的本质是补齐 Electron 及其 native 模块尤其是native-keymap的编译期与运行期系统依赖git、build-essential提供工具链xorg-devFedora 上为xorg-x11-server-devel libxkbfile-devel提供 X11/XKBfile 开发库。安装时牢记两点用 nvm 管理 Node 版本20.19.0、不用sudo跑 pnpm。三个常见报错分别对应缺编译期头文件缺运行期共享库store 属主错乱均可通过本文给出的命令对症修复。完整的构建流程与更细的发行版差异可继续阅读 packages/website/content/docs/dev/BUILD.md 与 packages/website/content/docs/dev/README.md。【免费下载链接】marktextA simple and elegant markdown editor, available for Linux, macOS and Windows.项目地址: https://gitcode.com/gh_mirrors/ma/marktext创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考