EN
开始使用
核心功能
深度集成
帮助
帮助

Linux / WSL 排查指南

本文是 常见问题解答 (Q&A) 中 Linux / WSL 问题的完整排查指南，适用于在 Linux 桌面或 Windows WSLg 环境中使用 ZCode Linux 版的用户。如果遇到 AppImage 无法启动、登录后没有自动回到 ZCode、中文输入法无法使用、或 WSLg 下首个中文字符不显示等问题，可以按本文步骤逐项检查。

推荐使用方式

  • 请使用普通用户启动 ZCode，不建议使用 sudo 启动。
  • deb 和 AppImage 建议选择一种安装方式使用，避免多个版本互相覆盖系统打开方式。
  • 如果使用 AppImage，建议放在固定路径（例如 ~/Applications/ZCode.AppImage），不要在登录前后移动文件。
  • 在 WSLg 中使用时，建议从同一个 WSL/Linux 环境内启动 ZCode 和浏览器。
  • 中文输入法建议使用系统中已经配置好的 IBus 或 Fcitx5。

AppImage 无法启动

缺少 libfuse2

部分较新的 Linux 发行版默认只安装 FUSE 3，而 AppImage 可能需要 libfuse.so.2。常见报错：

dlopen(): error loading libfuse.so.2
AppImages require FUSE to run.

Ubuntu / Debian 用户可尝试：

sudo apt update
sudo apt install libfuse2

如果当前发行版仓库不提供 libfuse2，请参考发行版官方文档安装 FUSE 2 兼容包。

点击图标无反应

如果从应用菜单点击无反应，请先从终端启动一次，查看具体错误：

~/Applications/ZCode.AppImage

建议优先使用 deb 安装版。

NVIDIA / GPU 相关启动问题

如果终端中出现 GPU 进程不可用、NVIDIA 或渲染相关错误，可以尝试用软件渲染方式启动：

~/Applications/ZCode.AppImage \
  --disable-gpu \
  --disable-software-rasterizer \
  --use-gl=swiftshader

如果仍无法启动，可再临时加上 --no-sandbox 验证：

~/Applications/ZCode.AppImage \
  --no-sandbox \
  --disable-gpu \
  --disable-software-rasterizer \
  --use-gl=swiftshader

--no-sandbox 仅建议用于定位或临时绕过启动问题。长期使用前，请优先尝试 deb 安装版。

建议的 AppImage 放置方式

建议将 AppImage 放到固定目录：

mkdir -p ~/Applications
mv ~/Downloads/ZCode*.AppImage ~/Applications/ZCode.AppImage
chmod +x ~/Applications/ZCode.AppImage

之后从固定路径启动：

~/Applications/ZCode.AppImage

如果需要固定启动参数，可以创建一个简单的启动脚本：

cat > ~/Applications/zcode-launcher.sh << 'EOF'
#!/usr/bin/env bash
exec "$HOME/Applications/ZCode.AppImage" \
  --disable-gpu \
  --disable-software-rasterizer \
  --use-gl=swiftshader \
  "$@"
EOF
chmod +x ~/Applications/zcode-launcher.sh

之后使用：

~/Applications/zcode-launcher.sh

如果你的环境必须使用 --no-sandbox 才能启动，可以临时把它加入启动脚本。

登录后没有回到 ZCode

ZCode 登录完成后，浏览器需要把结果交回 ZCode。如果系统没有正确关联 ZCode，或者当前运行的版本和系统关联的版本不一致，就可能出现浏览器登录完成但 ZCode 没反应。

请先确认 ZCode 是普通用户启动：

id -u

如果输出是 0，说明当前是 root 用户。请关闭 ZCode 后用普通用户重新启动。

继续检查系统是否能找到 ZCode 的打开方式：

xdg-mime query default x-scheme-handler/zcode

正常情况下应能看到与 ZCode 相关的 desktop 文件，例如：

zcode.desktop

如果没有输出，或输出明显不是 ZCode，请先重新启动一次 ZCode。AppImage 用户建议从固定路径重新启动：

~/Applications/ZCode.AppImage

然后再次执行：

xdg-mime query default x-scheme-handler/zcode

AppImage 登录回调注意事项

下面这些情况容易导致登录完成后无法回到 ZCode：

  • AppImage 启动后被移动、重命名或删除。
  • 同时安装了 deb 版和 AppImage 版。
  • 曾经用 sudo 启动过 AppImage。
  • 系统仍然关联到旧版本 ZCode。
  • 当前启动方式依赖特殊参数，但系统打开方式没有使用相同参数。

建议处理方式：

  1. 关闭所有 ZCode 窗口。
  2. 将 AppImage 放到固定目录。
  3. 从固定路径重新启动 ZCode。
  4. 重新检查系统打开方式：
xdg-mime query default x-scheme-handler/zcode

如果你使用了自定义启动脚本，也可以确认桌面文件是否指向该脚本：

grep -n "Exec=" ~/.local/share/applications/zcode.desktop 2>/dev/null || true

deb 用户注意事项

如果使用 deb 安装版，请尽量不要同时运行 AppImage 版。若之前用过 AppImage，建议先关闭所有 ZCode 窗口，再从系统应用菜单或命令行启动 deb 版：

zcode

如果登录仍无法回到 ZCode，请把下面命令的输出通过 用户反馈渠道 发给我们：

xdg-mime query default x-scheme-handler/zcode
ps -ef | grep -i '[Z]Code' || true

中文输入法无法使用

如果在 ZCode 中只能输入英文，通常和当前 Linux/WSLg 会话的输入法环境有关。请先确认输入法服务是否正常：

echo "$GTK_IM_MODULE"
echo "$QT_IM_MODULE"
echo "$XMODIFIERS"
ibus engine 2>/dev/null || true
fcitx5-remote 2>/dev/null || true

IBus 用户

可以尝试从已配置 IBus 的 shell 中启动 ZCode：

export GTK_IM_MODULE=ibus
export QT_IM_MODULE=ibus
export XMODIFIERS=@im=ibus
ibus-daemon -drx
~/Applications/ZCode.AppImage

如果你使用 deb 版，把最后一行替换为：

zcode

Fcitx5 用户

可以尝试：

export GTK_IM_MODULE=fcitx
export QT_IM_MODULE=fcitx
export XMODIFIERS=@im=fcitx
fcitx5 -d
~/Applications/ZCode.AppImage

如果你使用 deb 版，把最后一行替换为：

zcode

WSLg 下首个中文字符不显示

部分 WSLg + IBus 环境中，可能出现首次切换到中文输入时，第一个字符没有立即显示，需要先输入一个英文字符，后续中文才正常显示。

这是 WSLg 输入法链路中的已知兼容性问题。当前可以尝试以下方式缓解：

  • 从已经配置好输入法环境变量的 shell 启动 ZCode。
  • 尝试切换到 Fcitx5。
  • 切换输入法后先输入一个占位字符再删除。

反馈问题时请提供的信息

如果按以上步骤仍无法解决，请把以下信息通过 用户反馈渠道 发给我们：

echo "WSL_DISTRO_NAME=$WSL_DISTRO_NAME"
echo "XDG_SESSION_TYPE=$XDG_SESSION_TYPE"
echo "DISPLAY=$DISPLAY"
echo "WAYLAND_DISPLAY=$WAYLAND_DISPLAY"
echo "BROWSER=$BROWSER"

id -u
which xdg-open || true
which xdg-mime || true
xdg-mime query default x-scheme-handler/zcode || true
grep -n "Exec=" ~/.local/share/applications/zcode.desktop 2>/dev/null || true
ps -ef | grep -i '[Z]Code' || true

echo "GTK_IM_MODULE=$GTK_IM_MODULE"
echo "QT_IM_MODULE=$QT_IM_MODULE"
echo "XMODIFIERS=$XMODIFIERS"
ibus engine 2>/dev/null || true
fcitx5-remote 2>/dev/null || true

如果使用 AppImage，也请补充：

ls -l ~/Applications/ZCode.AppImage 2>/dev/null || true

了解更多

安装

下载并安装 ZCode 桌面应用。

用户反馈与支持

遇到问题时，了解如何提供有效反馈。

常见问题解答 (Q&A)

查看安装、配置与使用中的常见疑问。