Linux / WSL 排查指南

Linux 与 WSLg 环境下的安装、登录回调与中文输入法排查指南。

帮助企业版中文

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

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 才能启动，可以临时把它加入启动脚本。

登录后没有回到澄宇AI工作台

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

请先确认澄宇AI工作台是普通用户启动：

id -u

如果输出是 0，说明当前是 root 用户。请关闭澄宇AI工作台后用普通用户重新启动。

继续检查系统是否能找到澄宇AI工作台的打开方式：

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

正常情况下应能看到与澄宇AI工作台相关的 desktop 文件，例如：

zcode.desktop

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

~/Applications/ZCode.AppImage

然后再次执行：

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

AppImage 登录回调注意事项

下面这些情况容易导致登录完成后无法回到澄宇AI工作台：

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

建议处理方式：

关闭所有澄宇AI工作台窗口。
将 AppImage 放到固定目录。
从固定路径重新启动澄宇AI工作台。
重新检查系统打开方式：

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

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

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

deb 用户注意事项

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

zcode

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

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

中文输入法无法使用

如果在澄宇AI工作台中只能输入英文，通常和当前 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 中启动澄宇AI工作台：

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 启动澄宇AI工作台。
尝试切换到 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 开源项目文档整理，并按澄宇AI工作台企业版修订。

推荐使用方式