docs: 补充 Deepin 25/Linux 打包安装指南#566
Conversation
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces packaging and installation support for Deepin 25, adding desktop launcher configurations, build and installation bash scripts, and a detailed markdown guide. The reviewer provided several constructive suggestions to improve the robustness of the scripts, including creating a temporary wrapper script for pnpm instead of searching inside ~/.npm/_npx, using pnpm exec to run local binaries, converting the target .deb path to an absolute path via realpath to prevent apt lookup issues, and running gtk-update-icon-cache with sudo to ensure global icon cache updates succeed.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
| ensure_pnpm() { | ||
| if command -v pnpm >/dev/null 2>&1; then | ||
| return | ||
| fi | ||
|
|
||
| log "pnpm not found; preparing temporary pnpm via npm exec" | ||
| ensure_command npm | ||
| npm_config_registry="$REGISTRY" npm exec --yes pnpm@10 -- --version >/dev/null | ||
|
|
||
| local pnpm_bin | ||
| pnpm_bin="$(find "$HOME/.npm/_npx" -path '*/node_modules/.bin/pnpm' -type f 2>/dev/null | sort | tail -n 1 || true)" | ||
| [[ -n "$pnpm_bin" ]] || fail "Unable to locate pnpm under $HOME/.npm/_npx" | ||
| export PATH="$(dirname "$pnpm_bin"):$PATH" | ||
| } |
There was a problem hiding this comment.
在没有全局 pnpm 的情况下，通过 find 命令在 ~/.npm/_npx 目录下查找 pnpm 二进制文件是非常脆弱且依赖于 npm 内部实现的做法。不同版本的 npm 缓存结构可能不同，且在某些受限环境（如容器或只读家目录）下可能会失败。
建议采用创建临时包装脚本（Wrapper Script）并将其加入 PATH 的方式。这种方式更加标准、健壮，且不依赖于 npm 的内部缓存路径设计。
| ensure_pnpm() { | |
| if command -v pnpm >/dev/null 2>&1; then | |
| return | |
| fi | |
| log "pnpm not found; preparing temporary pnpm via npm exec" | |
| ensure_command npm | |
| npm_config_registry="$REGISTRY" npm exec --yes pnpm@10 -- --version >/dev/null | |
| local pnpm_bin | |
| pnpm_bin="$(find "$HOME/.npm/_npx" -path '*/node_modules/.bin/pnpm' -type f 2>/dev/null | sort | tail -n 1 || true)" | |
| [[ -n "$pnpm_bin" ]] || fail "Unable to locate pnpm under $HOME/.npm/_npx" | |
| export PATH="$(dirname "$pnpm_bin"):$PATH" | |
| } | |
| ensure_pnpm() { | |
| if command -v pnpm >/dev/null 2>&1; then | |
| return | |
| fi | |
| log "pnpm not found; preparing temporary pnpm wrapper" | |
| ensure_command npm | |
| local tmp_bin_dir | |
| tmp_bin_dir="$(mktemp -d)" | |
| trap 'rm -rf "$tmp_bin_dir"' EXIT | |
| cat << EOF > "$tmp_bin_dir/pnpm" | |
| #!/bin/sh | |
| export NPM_CONFIG_REGISTRY="$REGISTRY" | |
| exec npm exec --yes pnpm@10 -- "\$@" | |
| EOF | |
| chmod +x "$tmp_bin_dir/pnpm" | |
| export PATH="$tmp_bin_dir:\$PATH" | |
| } |
| DEB_PATH="${1:-$(find_latest_deb)}" | ||
| [[ -f "$DEB_PATH" ]] || fail "Package not found: $DEB_PATH" |
There was a problem hiding this comment.
如果用户传入了一个相对路径（例如 dist/ZTools_2.6.1_amd64.deb），在执行 apt install 时，apt 可能会因为路径不包含 ./ 或不是绝对路径而将其误判为软件源中的包名，导致安装失败。
建议使用 realpath 将 DEB_PATH 转换为绝对路径，这样可以确保 apt 或 dpkg 能够正确识别并安装本地文件。
| DEB_PATH="${1:-$(find_latest_deb)}" | |
| [[ -f "$DEB_PATH" ]] || fail "Package not found: $DEB_PATH" | |
| DEB_PATH="${1:-$(find_latest_deb)}" | |
| [[ -f "$DEB_PATH" ]] || fail "Package not found: $DEB_PATH" | |
| DEB_PATH="$(realpath "$DEB_PATH")" |
| log "Building Electron app" | ||
| ./node_modules/.bin/electron-vite build | ||
|
|
||
| log "Packaging Linux $ARCH artifacts" | ||
| ./node_modules/.bin/electron-builder --linux --"$ARCH" |
There was a problem hiding this comment.
直接调用 ./node_modules/.bin/ 下的二进制文件依赖于特定的目录结构。在 pnpm 环境下，使用 pnpm exec 来执行本地依赖的二进制文件是更推荐、更健壮的做法，它能自动处理路径解析和环境变量。
| log "Building Electron app" | |
| ./node_modules/.bin/electron-vite build | |
| log "Packaging Linux $ARCH artifacts" | |
| ./node_modules/.bin/electron-builder --linux --"$ARCH" | |
| log "Building Electron app" | |
| pnpm exec electron-vite build | |
| log "Packaging Linux $ARCH artifacts" | |
| pnpm exec electron-builder --linux --"$ARCH" |
| if [[ -f /usr/share/icons/hicolor/1024x1024/apps/ztools.png ]] && command -v gtk-update-icon-cache >/dev/null 2>&1; then | ||
| gtk-update-icon-cache -q /usr/share/icons/hicolor 2>/dev/null || true | ||
| fi |
There was a problem hiding this comment.
由于 /usr/share/icons/hicolor 是系统全局目录，非 root 用户运行 gtk-update-icon-cache 会因为权限不足而失败（虽然这里重定向了错误输出，但实际上缓存并没有被更新）。
建议使用 sudo 来执行该命令，以确保图标缓存能够成功刷新，从而使应用图标在桌面上立即生效。
| if [[ -f /usr/share/icons/hicolor/1024x1024/apps/ztools.png ]] && command -v gtk-update-icon-cache >/dev/null 2>&1; then | |
| gtk-update-icon-cache -q /usr/share/icons/hicolor 2>/dev/null || true | |
| fi | |
| if [[ -f /usr/share/icons/hicolor/1024x1024/apps/ztools.png ]] && command -v gtk-update-icon-cache >/dev/null 2>&1; then | |
| sudo gtk-update-icon-cache -q /usr/share/icons/hicolor 2>/dev/null || true | |
| fi |
1 participant
说明
本 PR 补充了 Deepin 25 / Linux 环境下的打包和安装说明，并提供两个脚本：
docs/deepin25/build-deepin25.sh：一键编译 Linux 包docs/deepin25/install-deepin25.sh：一键安装 deb 包，并创建桌面图标和应用菜单入口这次整理主要解决 Deepin 25 下从源码打包、安装、创建启动器时容易遇到的问题，包括：
验证
已在 Deepin 25 amd64 环境验证：
ztools启动~/.local/share/applications/ztools.desktop可正常创建备注
感谢 ZTools 社区和维护者持续开放源码，让 Linux 用户也可以自行编译、排查和改进使用体验。这个项目对启动器、插件系统和自动化能力的探索很有价值，开源让更多用户能参与测试和补充不同系统环境下的适配经验。
也希望后续官方发布包可以包含 Linux 版本。这样 Deepin、Ubuntu、Debian 等发行版用户可以更方便地安装和更新，也能降低新用户尝试 ZTools 的门槛。