# terminal-ts **Repository Path**: opentj/terminal-ts ## Basic Information - **Project Name**: terminal-ts - **Description**: 跨操作系统的Terminal - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 1 - **Created**: 2026-09-19 - **Last Updated**: 2026-11-09 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Terminal (Tauri) 用 [Tauri 2](https://tauri.app) 实现的桌面终端模拟器。 A desktop terminal emulator built with [Tauri 2](https://tauri.app). ## 功能 / Features - **Shell 自动检测 / Automatic shell detection**: - Windows: 优先级 `pwsh` → `powershell` → `cmd` (priority order) - 非 Windows: 父进程链里最近的交互式 shell → 账号登录 shell(macOS 查 `dscl`,其他系统查 `/etc/passwd`)→ `$SHELL` → `/bin/sh`;配置里的 `shell` 仍最优先 / on Unix: the nearest interactive shell in the parent chain → the account's login shell (`dscl` on macOS, `/etc/passwd` elsewhere) → `$SHELL` → `/bin/sh`; a configured `shell` still wins - **真实 PTY 会话 / Real PTY sessions**:Windows 使用 ConPTY,其他平台使用 Unix PTY,交互式程序(vim、htop 等)完整可用 / ConPTY on Windows, Unix PTY elsewhere; interactive programs (vim, htop, …) work fully - **支持管道、重定向 / Pipes & redirection**:`ls -la | grep rust`、`echo hello > file.txt`、`cat < input.txt` - **多标签页 / Multiple tabs**:新建(+ / Ctrl+Shift+T)、关闭(× / 鼠标中键 / Ctrl+Shift+W)、切换(Ctrl+Tab / Ctrl+PageUp·PageDown)/ new (+ / Ctrl+Shift+T), close (× / middle-click / Ctrl+Shift+W), switch (Ctrl+Tab / Ctrl+PageUp·PageDown) - **标签页重命名 / Rename tabs**:双击 tab 或按 F2 改名,Enter 提交、Esc 取消;右键菜单可“恢复自动标题”(回到 shell 通过 OSC 0/2 给的标题,清空输入提交同效);窗口标题随之更新 / double-click a tab or press F2 to rename it (Enter commits, Esc cancels); the context menu restores the shell-provided title (submitting an empty name does the same); the window title follows - **复制粘贴 / Copy & paste**:Ctrl+Shift+C 复制选中、Ctrl+Shift+V 粘贴、右键(有选中→复制,无选中→粘贴)/ copy selection (Ctrl+Shift+C), paste (Ctrl+Shift+V), right-click (copy if selection, else paste) - **终端内搜索 / In-terminal search**:Ctrl+Shift+F,Enter/Shift+Enter 下一个/上一个,Esc 关闭 / open with Ctrl+Shift+F; Enter / Shift+Enter for next / previous; Esc closes - **退出确认 / Quit confirmation**:关闭窗口(或 macOS `Cmd+Q`)时,若存在改过名的标签或有进程仍在运行(前台作业,或存活 ≥2 秒的后台子进程),会列出这些标签并标注原因;点某一项可跳回该标签,Esc / 取消则放弃。关闭单个标签时,只有该标签还有进程在跑才会确认 / closing the window (or `Cmd+Q` on macOS) lists tabs that were renamed or still have a running process (a foreground job, or a background child older than 2s) and asks first; click an entry to jump back to that tab, Esc / Cancel aborts. Closing a single tab only asks when that tab still has a running process - **字体缩放 / Font zoom**:Ctrl+= / Ctrl+- 缩放、Ctrl+0 复位 / zoom with Ctrl+= / Ctrl+-, reset with Ctrl+0 - **配置文件 / Config file**:`config.json` 可覆盖 shell、字体、字号、主题等,首次运行自动生成 / `config.json` overrides shell, font, size, theme, etc.; auto-created on first run - **主题 / Themes**:dark、light、solarized-dark、dracula、tokyo-night 或跟随系统深色模式 / preset themes or follow the OS dark/light mode - **窗口标题联动 / Window title sync**:shell 通过 OSC 0/2 设置标题时,同步更新窗口标题 / window title follows the shell's OSC 0/2 title - **单实例 / Single instance**:重复启动时聚焦已有窗口,不新开 / a second launch focuses the existing window instead of duplicating - **窗口状态记忆 / Window state**:记住窗口位置与大小,重启恢复 / window position and size are remembered across restarts - **tab 切换保留历史 / Tab history preserved**:切换标签页时终端的命令历史与输出完整保留 / switching tabs keeps each terminal's history intact - 进程退出后自动关闭该标签页;若为最后一个标签页则关闭窗口 / auto-closes the tab when the shell exits; closes the window when it was the last tab ## 配置 / Configuration 配置文件位于应用配置目录,首次运行自动生成(默认值可直接改): - **Windows**: `%APPDATA%\dev.taiji.terminal\config.json` - **macOS**: `~/Library/Application Support/dev.taiji.terminal/config.json` - **Linux**: `~/.config/dev.taiji.terminal/config.json` | 字段 / Field | 类型 | 说明 / Meaning | |---|---|---| | `shell` | string \| null | 覆盖 shell 检测(如 `"pwsh"`、`"cmd"`、`"bash"`);null = 自动检测 | | `font_size` | number | 字号(默认 20) | | `font_family` | string \| null | 覆盖运行时字体探测(如 `"JetBrainsMono NFM"`);null = 自动 | | `theme` | string | `dark` / `light` / `solarized-dark` / `dracula` / `tokyo-night` / `followSystem` | | `cursor_blink` | boolean | 光标闪烁(默认 true) | | `scrollback` | number | 回滚行数(默认 10000) | | `start_cwd` | string \| null | 新 shell 的起始目录;null = 用户主目录 | | `confirm_on_running_processes` | boolean | 有进程仍在运行时是否弹确认(默认 true);关掉后只在改过名的标签上提醒 | 修改后重启应用生效。示例:使用 Tokyo Night 主题 + 16px 字号: `"theme": "tokyo-night", "font_size": 16` ## 中文 / 图标显示 · Chinese / icon rendering 终端基于 **xterm ≥ 6.0.0**(5.4+ 起只有 DOM 渲染器——canvas 渲染器与 `rendererType` 选项已移除;**6.0.0 修复了 DOM 渲染器不绘制空格背景的问题**,oh-my-posh 的 `空格✓空格` 蓝色段才能正常显示,因此不要降级到 5.5 及更早)。字体链在 `src/lib/fonts.ts` 里用哨兵字体探测(`14px "X", monospace` vs `14px "__missing__", monospace` 的宽度对比,先 `await document.fonts.ready`)挑出本机已安装字体,优先级(最佳在前): ``` ① 带连字的 Nerd Font(JetBrainsMono/FiraCode/CaskaydiaCove Nerd Font,连字 + 图标一个字体搞定) → ② 纯连字等宽(JetBrains Mono / Fira Code / Cascadia Code,连字生效,图标回退到后面的 Nerd Font) → ③ 纯 Nerd Font(MesloLGM 等,图标保证、无连字) → ④ 系统等宽(Menlo)→ CJK(Sarasa Mono SC 优先,中文等宽)→ monospace ``` - **连字字体优先**:只有让 JetBrains Mono / Fira Code / Cascadia 等带 `calt` 连字字形的字体排在链首,`->`、`=>`、`===` 才会渲染成连字;且探测阈值必须低(0.1)——JetBrains Mono 与 Menlo 的字宽差仅 ~0.4px,0.5 会漏判成"不可用"。**不要用 `serif`/`sans`/单独的 `monospace` 作探测基准**:未知字体会落回默认字体而非该泛型(`serif` 会误判),而 `monospace` 在 macOS 就是 Menlo 会互相抵消。 - **Nerd Font 必须放在中文字体之前**:oh-my-posh 等提示符使用 Nerd Font / powerline 私有区图标(U+E0B0–U+E0B6、U+EA83、U+F00C 等)。中文字体(微软雅黑/宋体/PingFang)会把私有区码位错误映射成汉字字形,导致显示为 `瞵間` 类乱码;Nerd Font 优先可保证图标正确渲染。 **Nerd Font must come before CJK fonts**: prompts like oh-my-posh use private-use-area (PUA) glyphs from Nerd Font / powerline (U+E0B0–U+E0B6, U+EA83, U+F00C, …). CJK fonts (Microsoft YaHei/SimSun/PingFang) mis-map those PUA codepoints to CJK ideographs, producing mojibake like `瞵間`; putting the Nerd Font first renders the icons correctly. - **CJK 等宽优先用更纱黑体(Sarasa Mono SC / Sarasa Term SC)**:Sarasa 的西文来自 Iosevka、中文来自思源黑体,Mono/Term 变体把 CJK 字形调整到恰好 2 倍西文宽度,中文在终端里保持等宽网格。其 PUA 图标只有部分 powerline 箭头(无完整 Nerd 集),因此排在 Nerd Font 之后——图标仍由 Nerd Font 渲染,中文回退到 Sarasa。字体链已内置,安装后自动生效;未安装时自动回退到系统 CJK 字体(PingFang SC / 微软雅黑),Linux 尾部兜底文泉驿正黑(WenQuanYi Zen Hei)与 Droid Sans Fallback(麒麟/老系统预装)。 - **macOS 下安装 Nerd Font**(Homebrew 已合并 cask-fonts 仓库,直接安装即可)/ Install a Nerd Font on macOS: ```bash brew install --cask font-meslo-lg-nerd-font # 推荐 / recommended(与 Windows 一致) # 其他可选 / alternatives: font-jetbrains-mono-nerd-font, font-fira-code-nerd-font, font-hack-nerd-font ``` 未安装任何 Nerd Font 时,程序会自动降级到已装的等宽字体(如 JetBrains Mono / Menlo),但 oh-my-posh 图标可能显示为方块。 - **连字 / Ligatures**(`@xterm/addon-ligatures`):JetBrains Mono / Fira Code 等带 `calt` 连字字形的字体可渲染 `->`、`=>`、`===` 等连字。Tauri WebView 无 Local Font Access API,插件走 fallback 匹配;无连字字形的字体(Menlo 等)原样显示,不受影响。 - **编码管道为纯 UTF-8 字节透传**(ConPTY 输入/输出本身是 UTF-8),不要在 Rust / JS 层做 GBK 等转码。 **The pipeline is raw UTF-8 bytes end to end** (ConPTY I/O is UTF-8 already); do not add GBK or other transcoding in the Rust/JS layer. ## 启动横幅 / Startup banner pwsh 启动时的版本横幅、更新提示、profile 加载耗时提示已在 `spawn_shell`(`src-tauri/src/lib.rs`)中抑制。 The pwsh version banner, update notice and profile-load-time message are suppressed in `spawn_shell` (`src-tauri/src/lib.rs`): | 提示内容 / Message | 抑制方式 / How to suppress | |---|---| | `PowerShell 7.6.4`(版本横幅 / version banner) | `-NoLogo` | | `A new PowerShell stable release is available...`(更新提示 / update notice) | 环境变量 `POWERSHELL_UPDATECHECK=Off` | | `Loading personal and system profiles took Xms.`(加载耗时 / load time) | `-NoProfileLoadTime`(仅 pwsh,powershell 5.1 不识别 / pwsh only; PS 5.1 doesn't recognize it) | 另:pwsh 启动参数含 `-NoExit -Command "$PSStyle.OutputRendering='Ansi'"`——ConPTY 下默认 `Host` 模式会剥掉提示符的 ANSI 颜色,强制 `Ansi` 保证 oh-my-posh 段正常着色。/ pwsh is launched with `-NoExit -Command "$PSStyle.OutputRendering='Ansi'"` — under ConPTY the default `Host` mode strips ANSI from the prompt; forcing `Ansi` keeps oh-my-posh segments colored. ## 运行(开发)/ Run (dev) ```bash npm install npm run tauri dev ``` ## 构建 / Build ```bash npm run tauri build ``` ### Linux 系统依赖 / Linux system dependencies Tauri 在 Linux 上走 CGO + `pkg-config` 找系统的 GTK 与 webview,**只有运行时包不够,得装 `-dev` 包**, 否则 `cargo build` 会停在 `Package gtk+-3.0 was not found in the pkg-config search path`。 Tauri links GTK and the webview through CGO + `pkg-config` on Linux; runtime libraries are **not** enough — without the `-dev` packages `cargo build` stops at the `pkg-config` search path. ```bash sudo apt-get update && sudo apt-get install -y \ libwebkit2gtk-4.1-dev \ build-essential curl wget file \ libxdo-dev libssl-dev \ libayatana-appindicator3-dev \ librsvg2-dev patchelf xdg-utils libfuse2 ``` 后四个只有**打包**才要,编二进制本身不需要:`librsvg2-dev` 与 `patchelf` 供 AppImage 的 linuxdeploy gtk 插件、`libfuse2` 供 AppImage 运行时、`xdg-utils` 供桌面集成。只要裸可执行文件 (`npm run tauri build -- --no-bundle`)时可以省掉 `patchelf xdg-utils libfuse2`。 The last four are **bundler-only**: `librsvg2-dev` + `patchelf` for linuxdeploy's GTK plugin, `libfuse2` for the AppImage runtime, `xdg-utils` for desktop integration. Drop `patchelf xdg-utils libfuse2` when building a bare binary (`npm run tauri build -- --no-bundle`). 这份清单与 `.github/workflows/release.yml` 里「Install Linux dependencies」那一步一致 —— 改一处要改两处。 Same list as the "Install Linux dependencies" step in `.github/workflows/release.yml` — change both together. Ubuntu 24.04 起系统里只有 `webkit2gtk-4.1`,Tauri 2 要的正好是它(Wails v2 那边才是 `4.0`)。 Windows / macOS 无需额外安装:WebView2 随 Win10/11 的 Edge 预装,macOS 用系统 WKWebView。 Nothing extra on Windows / macOS: WebView2 ships with Edge on Win10/11, macOS uses the system WKWebView. ### AppImage(需要联网)/ AppImage (needs network) Linux 上默认的 `npm run tauri build` 只出 **deb + rpm**(`src-tauri/tauri.linux.conf.json` 把 `bundle.targets` 收窄成 `["deb", "rpm"]`;macOS / Windows 仍走主配置的 `"all"`,产出 dmg / msi)。 **CI 不受影响**:`.github/workflows/release.yml` 对 Linux 显式传 `--bundles deb,rpm,appimage`, 所以 tag 触发的 Release 依然包含 AppImage。AppImage 被单独拎出来,是因为 linuxdeploy 的 appimage 插件 **每次构建都会从 GitHub 现下载 type2-runtime**(约 944 KB,没有本地缓存);GitHub 不通时 Tauri 只会打印一句 `failed to run linuxdeploy`,看不出真实原因。 On Linux the default `npm run tauri build` produces **deb + rpm only** (`src-tauri/tauri.linux.conf.json` narrows `bundle.targets` to `["deb", "rpm"]`; macOS / Windows keep `"all"` from the main config and still get dmg / msi). **CI is unaffected**: `release.yml` passes `--bundles deb,rpm,appimage` on Linux, so tag-triggered releases still ship the AppImage. AppImage is a separate entry point because linuxdeploy's appimage plugin **downloads type2-runtime from GitHub on every build** (~944 KB, no local cache); when GitHub is unreachable Tauri only prints `failed to run linuxdeploy`. ```bash npm run build:appimage # 等价于 bash scripts/build-appimage.sh ``` 脚本会把 runtime 缓存到 `${XDG_CACHE_HOME:-~/.cache}/tauri/runtime-x86_64`,再通过插件支持的 `LDAI_RUNTIME_FILE` 传给它 —— **只有第一次需要联网**。想用自己已有的 runtime: The script caches the runtime at `${XDG_CACHE_HOME:-~/.cache}/tauri/runtime-x86_64` and hands it to the plugin via `LDAI_RUNTIME_FILE` — **only the first run needs the network**. To reuse your own copy: ```bash LDAI_RUNTIME_FILE=/path/to/runtime-x86_64 npm run tauri build -- --bundles appimage ``` 排查时加 `-v` 才能看到 linuxdeploy 的真实 stderr(例如 `Downloading runtime file from ...` 失败): Add `-v` when troubleshooting, otherwise linuxdeploy's real stderr is swallowed: ```bash npm run tauri build -- --bundles appimage -v ``` ## 单独构建/检查 / Build & check separately ```bash npm run build # 前端:vue-tsc + vite build(产物在 dist/)/ frontend → dist/ npm test # 前端测试:vitest / frontend unit tests cd src-tauri && cargo build # 后端:Rust / backend cd src-tauri && cargo test # 后端测试 / backend unit tests cd src-tauri && cargo clippy # Lint cd src-tauri && cargo fmt --check ``` ## 技术栈 / Tech stack - 后端 / Backend:Rust + Tauri 2 + `portable-pty`(会话管理、事件流 / sessions & event streaming)+ `tauri-plugin-single-instance` / `window-state` / `clipboard-manager` - 前端 / Frontend:Vue 3 + TypeScript + xterm.js 6(`@xterm/xterm` + `@xterm/addon-fit` / `addon-search` / `addon-ligatures`)+ Vite 8(Rolldown) - CI:GitHub Actions(`.github/workflows/ci.yml`,前端 build + vitest;后端双平台 fmt/clippy/test) ## 架构 / Architecture ``` 前端 / Frontend (WebView) └─ App.vue: 标签页管理(新建/关闭/切换 + 窗口标题联动)/ tab management + window title sync └─ TerminalView.vue: xterm.js 实例 / xterm.js instance │ invoke: spawn_shell / write_session / resize_session / kill_session / get_config / save_config ▼ 后端 / Backend (Rust) ├─ SessionManager: session id → PTY 会话 / session id → PTY session ├─ 读线程 / reader thread: shell 输出 → emit "terminal-output"(base64) / "terminal-exit" ├─ 退出监听 / exit watcher: 子进程退出 → 关闭 ConPTY → 触发 terminal-exit └─ 插件 / plugins: single-instance、window-state、clipboard-manager ```