桌面端 SSH 用戶端 · Windows / Linux / macOS

連接、終端、檔案
放進同一個視窗


LIULI Shell 是一款跨平台 SSH 用戶端。
它把連線管理、互動式終端、SFTP 檔案傳輸、執行狀態監控與設定同步整合到一個桌面應用程式中,適合需要同時維護多台伺服器的開發者與維運人員。

安裝版 / 免安裝版 跨平台雲端同步 可匯入 FinalShell 備份 8 套介面主題
LIULI Shell 主介面,左側伺服器與監控、中間終端與檔案、右側伺服器資訊與處理程序
工作階段多分頁 SSH 與斷線重連
檔案快速載入的 SFTP 增刪改查
監控資源、網路與處理程序
同步官方雲端服務/自訂 WebDAV
01 — 下載

選擇適合你的安裝方式

Windows 10 / 11 提供安裝版與免安裝版;Linux 與 macOS 使用原始碼建置。安裝版與免安裝版功能一致。

安裝版與免安裝版

安裝版帶安裝精靈並建立捷徑;免安裝版解壓即用,適合放在 USB 隨身碟或臨時環境。

Windows 10 / 11 x64 · Setup.exe / Portable.exe
提取碼 YKXY(連結已附,無需手動填寫)
開啟夸克網盤 ↗
GitHub

GitHub Releases

適合海外網路存取,發行版附件與儲存庫提交同步更新。

前往 GitHub Releases ↗
Gitee

Gitee Releases

適合國內網路存取,提供免安裝版附件,儲存庫與發行版保持同步。

前往 Gitee Releases ↗
原始碼建置

Linux / macOS

在目標系統上安裝相依套件並打包,支援 deb、AppImage、tar.gz 以及 macOS 的 dmg 與 zip。

查看建置指令
設定預設儲存在 %APPDATA%\LIULI Shell,升級或重新安裝不會刪除。更換電腦時,可以使用雲端同步備份,或在設定中匯出設定檔後移轉。
02 — 快速建置

從原始碼產生安裝包

Linux 與 macOS 需要在本機建置。下列指令請逐條執行,不要整段貼上。指令碼會識別發行版、安裝相依套件並詢問打包類型。

build.sh — quick start copy & run
Quick Build

Linux / macOS 建置指令

先選擇原始碼來源(Gitee 或 GitHub,二選一),再進入目錄執行建置指令碼。
Gitee 預設目錄為 liuli-shell,GitHub 預設目錄為 Liulishell;以下統一複製為 liuli-shell,後續指令保持一致。

需要 Git。步驟 0 安裝 Git;步驟 1 只保留一個原始碼來源;步驟 2 執行建置指令碼。複製完成後再執行建置指令。

# 0) 需要 Git;已安裝會自動略過(其他發行版換成 dnf / pacman)
command -v git >/dev/null || sudo apt-get update && sudo apt-get install -y git

# 1) 先刪除舊目錄,再複製原始碼(Gitee / GitHub 二選一)
# Gitee(國內推薦,預設目錄就是 liuli-shell)
rm -rf liuli-shell Liulishell && git clone https://gitee.com/liuliwanjiaweb/liuli-shell.git liuli-shell
# GitHub(海外推薦;預設目錄是 Liulishell,這裡明確指定為 liuli-shell)
rm -rf liuli-shell Liulishell && git clone https://github.com/LIULIWANJIA/Liulishell.git liuli-shell

# 2) 進入專案並建置:識別發行版 → 補系統相依套件 → 選 deb / AppImage → 打包 → 詢問安裝
cd liuli-shell && bash scripts/build-linux.sh

產物在 dist/。指令碼會提示選擇 1 = deb / 2 = AppImage / 3 = 兩者都要;只打 .tar.gz 使用 bash scripts/build-linux.sh tar。指令碼會自動處理 Ubuntu 24.04+ 的 *t64 套件名稱回退。CI 等非互動環境不會自動安裝,需要手動安裝產物。環境異常可先執行 bash scripts/build-linux.sh check 健檢;Electron 下載慢時指令碼會自動切換鏡像站。

相依套件缺失或建置失敗時 依序逐條執行,正常建置無需執行
# 3) 相依套件沒裝上或建置報錯時,再依序嘗試
bash scripts/build-linux.sh repair
bash scripts/build-linux.sh deps
bash scripts/build-linux.sh

基礎環境已安裝會自動略過。Homebrew 安裝過程需要輸入目前使用者密碼。複製後安裝相依套件並打包,Intel 與 Apple Silicon 可依需求選擇。

# 基礎環境(已裝過會自動略過;xcode-select 會彈窗,等安裝完成再繼續)
xcode-select --install 2>/dev/null || true
command -v brew >/dev/null || /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# 新裝 Homebrew 後加入目前終端 PATH(Intel 為 /usr/local/bin/brew)
if [ -x /opt/homebrew/bin/brew ]; then eval "$(/opt/homebrew/bin/brew shellenv)"; elif [ -x /usr/local/bin/brew ]; then eval "$(/usr/local/bin/brew shellenv)"; fi
# 需要 Node ≥ 18;缺失或版本過舊時安裝 20,然後驗證
node -v 2>/dev/null | grep -qE '^v(1[89]|[2-9][0-9])' || brew install node@20
brew link --overwrite --force node@20 >/dev/null 2>&1 || true
node -v && npm -v

# 先刪除舊目錄,再複製原始碼(Gitee / GitHub 二選一)
rm -rf liuli-shell Liulishell
# Gitee(國內推薦,預設目錄就是 liuli-shell)
git clone https://gitee.com/liuliwanjiaweb/liuli-shell.git liuli-shell
# GitHub(海外推薦;預設目錄是 Liulishell,這裡明確指定為 liuli-shell)
git clone https://github.com/LIULIWANJIA/Liulishell.git liuli-shell
cd liuli-shell npm ci || npm install # 失敗自動回退 npm install npm run vendor # 國內網路下載 Electron 慢時,先取消下面兩行註解(選用) # export ELECTRON_MIRROR=https://registry.npmmirror.com/-/binary/electron/ # export ELECTRON_BUILDER_BINARIES_MIRROR=https://registry.npmmirror.com/-/binary/electron-builder-binaries/ npm run dist:mac # x64 + arm64 一起產出 npx electron-builder --mac dmg zip --arm64 # 只打 Apple Silicon

產物在 dist/(.dmg / .zip)。npm run vendor 會複製 xterm 資源到 src/renderer/vendor,打包前必須執行;Intel 與 Apple Silicon 產物不能混用。未簽名應用程式被 Gatekeeper 攔截時,按右鍵「打開」放行。

國內網路建議使用 Gitee,Electron 下載慢時可以設定鏡像站變數。

03 — 資料移轉

FinalShell 備份匯入支援

支援匯入 FinalShell 匯出的 JSON 檔案或整個設定資料夾。匯入時會讀取連線資訊、重建群組層級,並在寫入前提供統計。

  • 兩種來源可以一次選擇多個 JSON,也可以直接選擇整個設定資料夾。
  • 層級還原依原始目錄結構建立最多三層群組,更深的目錄自動歸入對應的第一層群組。
  • 密碼處理解密後依本軟體的加密方式重新儲存;無法解開的項目會留空並明確提示。
  • 安全寫入匯入前先預覽將建立的群組與連線數量,重複項目自動略過;失敗不會影響既有設定。
匯入 FinalShell 設定 · LIULI Shell

匯入 FinalShell 設定

拖入檔案即可,支援一次選擇多個 JSON 或整個設定資料夾。

拖入 JSON 檔案或資料夾 也可以點擊下方按鈕選擇
選擇 JSON 檔案 選擇資料夾
預計:建立 2 個新第一層群組 3 個新第二層群組 1 個新第三層群組 共 14 個伺服器設定
自動:FinalShell 匯入(直接 JSON)

資料夾依層級自動建立群組(最多三層),第三層以下資料夾內的 JSON 歸入對應的第一層群組,不受目標群組影響。

開始匯入 匯入完成:新增 14,略過 2 個重複 · 建立群組:第一層 2 / 第二層 3 / 第三層 1
1選擇來源 選擇一個或多個 FinalShell JSON,也可以直接選擇整個設定資料夾。
2查看計畫 自動統計將建立的群組層級與連線數量,確認後再寫入。
3完成匯入 去除重複後寫入並重新整理清單,新群組預設收合,不中斷目前工作。
04 — 交流與回饋

取得協助與版本通知

使用問題、功能建議與版本動態會在群組中同步。選擇常用的平台加入即可。

QQ 群 · 國內

QQ 交流群

國內使用者可以透過 QQ 群回報問題、交流設定與使用經驗。

1127112572
加入 QQ 群 ↗
Telegram · 海外

TG 群組

海外使用者可以透過 Telegram 群組取得相同的通知與討論。

t.me/liulishell
開啟 TG 群組 ↗
05 — 核心模組

九個模組,涵蓋日常維運

從連線伺服器到傳輸檔案、查看狀態、移轉設定,主要操作都在用戶端內完成。以下依模組說明每個部分能做什麼。

01
▤

伺服器管理

用群組整理伺服器,支援多選、拖曳移動與複製設定;刪除的連線進入 30 天資源回收筒,可隨時還原。

02
❯_

終端工作階段

每個分頁對應獨立的 SSH 工作階段,支援指令歷史、快速輸入、斷線重連與分頁拖曳排序;代理連線帶有狀態標示。

03
▥

檔案管理

SFTP 目錄樹與檔案清單連動,終端切換目錄時自動跟隨;支援上傳下載、權限修改與內建文字編輯器。

04
◎

即時監控

持續收集 CPU、記憶體、Swap、磁碟、網路卡與處理程序資料,圖表刻度自動調整,異常負載可以直接定位。

05
⇅

傳輸中心

下載任務集中在獨立視窗管理,可暫停、取消或清空;即時顯示進度、速率與任務狀態。

06
☁

雲端同步

支援官方雲端服務與自訂 WebDAV:加密同步伺服器設定、群組與收藏,多裝置雙向合併;也可以手動同步或備份。

07
⇄

設定移轉

讀取 FinalShell 的 JSON 備份或整個設定目錄,依原始層級重建群組;匯入前先預覽,重複項目自動略過。

08
◐

外觀與互動

內建 8 套淺色與深色主題,字型、字級、介面縮放、滑鼠行為與快速鍵均可調整並自動儲存。

09
⌁

網路代理

為單一連線或全域設定 HTTP / SOCKS5 代理,支援預設代理與直連回退,適用內網與受限網路。

06 — 快捷指令

常用指令,點一下就能用

把高頻指令依模組整理,減少在終端裡反覆輸入長指令;需要修改時再交給指令編輯器。

Snippets & Command Editor

依模組整理,重複指令不再手打

常用、Docker、網路等模組分開管理,按鈕只顯示名稱,介面保持簡潔;模組與指令都支援拖曳排序。

  • 執行方式可設定單擊直接執行,或先填入指令框再確認。
  • 指令編輯器多行指令碼在右側編輯,Ctrl + Enter 傳送到目前工作階段。
  • 歷史與工作階段在歷史指令與目前工作階段之間切換,快速找回上一次輸入。
快捷指令SNIPPETS
常用Docker網路+
查看磁碟查看記憶體查看處理程序清除畫面
指令編輯器 Ctrl + Enter
1docker compose pull
2docker compose up -d
3docker compose ps
07 — 即時監控

資源、網路與處理程序,一個畫面掌握

連線後自動收集執行狀態,異常負載先在用戶端裡定位,再決定是否進入終端處理。

伺服器監控LIVE · 2s
CPU64%
記憶體62%
Swap14%
下行1.36 Mbps
上行0.21 Mbps
處理程序預覽 依 CPU 排序
nginx12.5%340 MB
worker-112.0%17.6 MB
worker-211.7%20.1 MB
worker-311.4%22.7 MB
Monitor & Processes

不用登入伺服器,也能先看狀態

左側顯示資源概覽,右側同步網路速率與處理程序占用;重新整理間隔與速率單位都可以在設定裡調整。

  • 資源概覽CPU、記憶體、Swap 與磁碟分割區使用率,圖表刻度自動調整。
  • 網路速率即時下行 / 上行與累計流量同畫面查看,單位可切換。
  • 處理程序預覽依 CPU 或記憶體排序,快速找到高占用處理程序。
08 — 資料與安全

設定留在本機,變更有備份

連線憑證、設定備份與刪除還原都在用戶端內完成,減少對額外服務與手動操作的依賴。

Local Data & Security

密碼加密儲存,誤刪可以還原

連線憑證只儲存加密字串,介面不回顯明文;設定寫入前自動備份,誤刪的伺服器與群組會進入資源回收筒。

  • 憑證保護密碼與金鑰使用本機金鑰加密,匯出設定時可再加密碼。
  • 自動備份寫入前產生備份,設定檔異常時可還原到最近一次。
  • 資源回收筒刪除的伺服器與群組保留 30 天,可隨時還原。
資料與安全LOCAL
✓
憑證加密儲存密碼與金鑰只儲存加密字串,介面不回顯明文。
✓
寫入前自動備份設定檔損壞時可還原到最近的備份。
✓
30 天資源回收筒誤刪的伺服器與群組可隨時還原。
✓
加密匯出 / 匯入換機移轉時可帶密碼匯出設定檔。
09 — 介面分區

主介面分為左、中、右三欄

三欄寬度可以拖曳調整,也可以依需求隱藏。頂端是工作階段分頁與視窗操作,底部狀態列顯示目前連線數。

左 伺服器與監控。群組清單、搜尋、連線狀態,以及 CPU、記憶體、Swap 與磁碟概覽。
中 工作區域。SSH 終端、指令列輸入、檔案管理員與快捷指令面板。
右 連線詳情。伺服器資訊、網路速率、處理程序清單與指令編輯器。
收起右欄後的終端工作區
終端工作區收起右欄,終端獲得更大空間
軟體設定中心
設定中心主題、字型、縮放與資料選項
快捷指令面板
快捷指令依模組整理,可直接執行
多語言

八種語言的介面與官網

用戶端介面與本站均已提供簡體中文、繁體中文、英語、俄語、法語、德語、日語與韓語版本。切換語言時頁面網址與 hreflang 標註同步變化,每種語言都對應同一套功能與截圖。

简体中文Chinese (Simplified) · zh-CN
繁體中文Chinese (Traditional) · zh-Hant
EnglishEnglish · en
日本語Japanese · ja
한국어Korean · ko
РусскийRussian · ru
FrançaisFrench · fr
DeutschGerman · de
10 — 設定與主題

依自己的工作方式調整

設定項目依用途分組,修改後立即生效並自動儲存。以下是最常用的六組選項。

LIULI Shell · 設定中心
LIULI Shell 設定中心
左側選單依用途分組,右側是目前分類的選項;底部可還原預設設定。

外觀與主題

  • 8 套配色,終端背景與 ANSI 色板同步切換
  • 三欄寬度、底部高度可拖曳並記憶
  • 不需要的模組可以單獨隱藏

字型與縮放

  • 中英文字型、字級與行距分別設定
  • 介面縮放 100 / 125 / 150 / 200%
  • 切換縮放需確認,Ctrl+Shift+0 可重設

滑鼠與快速鍵

  • 中鍵與右鍵的終端行為可調整
  • 全域快速鍵支援修改,衝突時即時提示
  • 快捷指令可拖曳排序

快捷指令

  • 依模組組織常用指令
  • 控制區固定在第一列,模組放不下時自動增列
  • 支援單擊直接執行或雙擊執行

同步與代理

  • WebDAV 位址、帳號與憑證分別儲存
  • 設定、群組與收藏雙向合併
  • 代理支援 HTTP / SOCKS5,可指定預設代理

資料與安全

  • 設定寫入前自動備份,異常時可還原
  • 密碼與金鑰只儲存加密字串,介面不回顯明文
  • 清空資料需要二次確認與倒數計時
Themes

8 套主題配色

淺色 6 套、深色 2 套;切換後介面、終端背景與 ANSI 配色同步變化。

暖白 · 墨綠預設 · 低對比護眼
霧藍 · 靛青清爽冷色
米杏 · 陶土溫暖紙感
石墨 · 冷灰中性高對比
夜間 · 深墨暗色介面
藕粉 · 莓紫柔和暖紫
青瓷 · 松綠淡雅青綠
深海 · 靛藍暗色藍調
11 — 進階參考

手動建置與排錯

需要手動控制建置流程、為不同發行版準備相依套件,或排查打包錯誤時,展開以下的完整參考。

Linux / macOS 完整建置指南 包含各發行版相依套件指令、AppImage / deb / dmg 打包、桌面圖示、FUSE 處理與常見報錯對照。 ▾

Linux x64(AppImage / .deb / tar.gz)

不同發行版的系統函式庫套件名稱不同,Ubuntu 24.04 起改為 *t64。三種產物用途:AppImage 免安裝、deb 走套件管理、tar.gz 解壓即用且不依賴 FUSE。

相容性要點:AppImage 只能執行在 glibc 不低於建置機的系統上。要在 20.04 ~ 26.04 通用,請在最舊的 Ubuntu 20.04 上建置;儲存庫裡的 scripts/build-linux.sh 會自動識別發行版並處理 t64 套件名稱回退。
不想手動安裝相依套件:bash scripts/build-linux.sh 一條指令完成「識別發行版 → 補系統相依套件 → 選套件類型 → 打包 → 詢問安裝」,已相容 apt / dnf / pacman。只想安裝相依套件用 ... deps,只健檢用 ... check,環境壞了用 ... repair。安裝階段:deb 走 apt install 並建立桌面圖示,AppImage 複製到 ~/Applications/LIULI-Shell 並產生應用程式選單與桌面圖示。

執行與安裝

chmod +x dist/LIULI-Shell-*-x86_64.AppImage
./dist/LIULI-Shell-*-x86_64.AppImage

# Debian / Ubuntu 安裝 deb
sudo apt install ./dist/LIULI-Shell-*_amd64.deb

# 解壓即用(不需要 FUSE,也不寫入系統目錄)
mkdir -p ~/Applications
tar -xzf dist/LIULI-Shell-*-x86_64.tar.gz -C ~/Applications
~/Applications/LIULI-Shell-*/liulishell

AppImage 執行報錯 dlopen(): error loading libfuse.so.2

AppImage 使用 type-2 執行階段,需要系統的 FUSE 2。Ubuntu 22.04 之前預設內建,24.04 / 26.04 需要手動安裝;沒裝 FUSE 也可以暫時解包執行。

# Ubuntu 24.04 / 26.04
sudo apt install -y libfuse2t64
# Ubuntu 20.04 / 22.04、Debian 12
sudo apt install -y libfuse2

# 不裝 FUSE 直接執行(啟動稍慢,功能一致)
./LIULI-Shell-*-x86_64.AppImage --appimage-extract-and-run

# 或者直接用 tar.gz 版本,完全不依賴 FUSE
新增應用程式清單圖示 / 桌面圖示(AppImage)
# 1) 放到固定位置
mkdir -p ~/Applications
cp dist/LIULI-Shell-*-x86_64.AppImage ~/Applications/LIULI-Shell.AppImage
chmod +x ~/Applications/LIULI-Shell.AppImage

# 2) 取出圖示(--appimage-extract 會在目前目錄解出 squashfs-root)
cd /tmp && ~/Applications/LIULI-Shell.AppImage --appimage-extract '*.png' >/dev/null 2>&1
mkdir -p ~/.local/share/icons/hicolor/512x512/apps
cp /tmp/squashfs-root/*.png ~/.local/share/icons/hicolor/512x512/apps/liulishell.png 2>/dev/null \
  || cp /tmp/squashfs-root/liulishell.png ~/.local/share/icons/hicolor/512x512/apps/ 2>/dev/null

# 3) 寫入應用程式清單項目($HOME 會展開成目前使用者目錄)
mkdir -p ~/.local/share/applications
cat > ~/.local/share/applications/LiuliShell.desktop <<EOF
[Desktop Entry]
Type=Application
Name=LIULI Shell
Comment=跨平台 SSH 終端與伺服器管理工具
Exec=$HOME/Applications/LIULI-Shell.AppImage %U
Icon=liulishell
Terminal=false
Categories=Development;System;Network;
StartupWMClass=LiuliShell
EOF
chmod +x ~/.local/share/applications/LiuliShell.desktop
update-desktop-database ~/.local/share/applications 2>/dev/null || true

# 4) 需要桌面圖示,再複製一份並標記為可信任
cp ~/.local/share/applications/LiuliShell.desktop ~/Desktop/
gio set ~/Desktop/LiuliShell.desktop metadata::trusted true 2>/dev/null || true
# 中文環境的桌面目錄可能是 ~/桌面,依實際情況替換

安裝 .deb 的使用者不需要這些步驟:deb 安裝時會自動寫入 /usr/share/applications,應用程式清單裡直接可見。

macOS(dmg + zip,x64 / arm64)

環境需求:macOS 12+(Intel 或 Apple Silicon),Xcode Command Line Tools、Homebrew、Git、Node.js 20/22 LTS。dmg 不能在 Windows / Linux 上建置。

1. 基礎工具(xcode-select 會彈窗,等待安裝完成再繼續)

xcode-select --install
/bin/bash -c "$(curl -fsSL \
  https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Apple Silicon 把 brew 寫入 PATH(Intel 為 /usr/local/bin/brew;重複執行不會重複附加)
grep -qsF 'brew shellenv' ~/.zshrc || echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc
source ~/.zshrc

2. Node 20 與 Git

brew install node@20 git
brew link --overwrite --force node@20
node -v && npm -v          # 期望輸出 v20.x

3. 原始碼與相依套件(先刪除舊目錄,避免殘留檔案導致異常;Gitee / GitHub 二選一。Gitee 預設目錄是 liuli-shell,GitHub 預設目錄是 Liulishell,這裡統一明確複製為 liuli-shell)

rm -rf liuli-shell Liulishell
# Gitee(國內推薦)
git clone https://gitee.com/liuliwanjiaweb/liuli-shell.git liuli-shell
# GitHub(海外推薦,取消下一行註解並註解上面的 Gitee 行)
# git clone https://github.com/LIULIWANJIA/Liulishell.git liuli-shell
cd liuli-shell
npm ci || npm install      # 鎖定檔與平台不一致時回退 npm install
npm run vendor             # 複製 xterm 資源到 src/renderer/vendor,打包前必須執行

4. 打包(只打目前架構最快;兩者都要就給 dist:mac)

npm run dist:mac                              # x64 + arm64 一起產出
npx electron-builder --mac dmg zip --arm64    # 只打 Apple Silicon
npx electron-builder --mac dmg zip --x64      # 只打 Intel

5. 產物與快取:產物在 ~/liuli-shell/dist/(*.dmg、*.zip);Electron 與打包工具的下載快取在 ~/Library/Caches/electron/、~/Library/Caches/electron-builder/,刪掉可強制重新下載。

6. 未簽名安裝:拖入「應用程式」後若被 Gatekeeper 攔截,按右鍵「打開」放行,或執行:

xattr -dr com.apple.quarantine "/Applications/LIULI Shell.app"
spctl --assess --type execute -vv "/Applications/LIULI Shell.app"   # 查看攔截原因

對外散布需要 Apple Developer ID 憑證並 notarize:設定 CSC_LINK(.p12 路徑或 base64)、CSC_KEY_PASSWORD;公證還需要 APPLE_ID、APPLE_APP_SPECIFIC_PASSWORD、APPLE_TEAM_ID,electron-builder 會自動完成簽名與公證。

Intel 與 Apple Silicon 的產物互不通用;想讓一個包支援兩種機器,用 npx electron-builder --mac dmg --universal(容量約為單一架構的兩倍,建置也明顯更慢)。

常見報錯對照表

報錯 / 現象原因與處理
無法定位套件 libasound2 Ubuntu 24.04 / Debian 13 起系統函式庫統一改名 *t64(例如 libasound2t64、libgtk-3-0t64)。先依舊名稱安裝、失敗自動回退:bash scripts/build-linux.sh deps 已內建該邏輯。
dlopen(): error loading libfuse.so.2 AppImage 執行時需要 FUSE 2:24.04+ 裝 libfuse2t64,22.04 及更早裝 libfuse2;不裝 FUSE 可用 --appimage-extract-and-run,或直接改用 .tar.gz。
Electron 下載逾時 / 卡在 downloading 設定鏡像站後重試:export ELECTRON_MIRROR=https://registry.npmmirror.com/-/binary/electron/、export ELECTRON_BUILDER_BINARIES_MIRROR=https://registry.npmmirror.com/-/binary/electron-builder-binaries/。
npm ci 失敗 / 鎖定檔與平台不一致 刪除 node_modules 後改用 npm install;Node 版本過舊(< 18)會直接裝不上,改用 Node 20。
rpmbuild not found 只有打 rpm 時才需要:Fedora 裝 rpm-build,Debian/Ubuntu 裝 rpm 與 rpm2cpio 相關套件,或先略過 rpm 目標。
Permission denied(執行 AppImage) 缺少執行權限:chmod +x dist/LIULI-Shell-*-x86_64.AppImage。
errSecInternalComponent / 簽名失敗(macOS) keychain 被鎖定:security unlock-keychain -p <密碼> ~/Library/Keychains/login.keychain-db 後重跑;CI 上還需 security set-key-partition-list。

通用說明

  • 建置目錄:所有產物預設輸出到專案根目錄 dist/。Linux 為 LIULI-Shell-*-x86_64 / *-arm64 的 .AppImage / .deb / .tar.gz(指令碼自動識別架構),macOS 為 .dmg / .zip。
  • 打包前必做:npm run vendor 會把 xterm.js 等前端資源複製到 src/renderer/vendor/,缺少這一步打出來的包終端會是空白。
  • 選建置機:AppImage 只能執行在 glibc 不低於建置機的系統上。要在 20.04 ~ 26.04 通用,就在最舊的 Ubuntu 20.04 上建置;只給自己用則本機建置最快。
  • 交叉建置:Linux 包在 Linux 建置、macOS 包必須在 macOS 建置,兩者產物互不通用;Windows 包同理。建議用對應系統的 CI(例如 ubuntu-22.04、macos-14 runner)產出安裝包。
  • 發布:把 dist/ 下對應平台的安裝包與免安裝包作為 Release 附件上傳(Windows 的 *.blockmap 僅用於差異更新,無需上傳);原始碼儲存庫不要提交 node_modules/ 與 dist/。