English | 中文

• main 分支：现有 1.x 版本，采用 Tauri + React 架构。
• gpui 分支：基于 Rust + GPUI 的全新 2.0.0 重构版本，与现有 Tauri 版本独立开发。

本文下方的功能、截图和构建说明针对 main 分支。了解 2.0.0 的实现与构建方式，请前往 gpui 分支查看对应文档。

说明：本文档中的界面截图可能与最新版本略有差异，当前截图拍摄于 v0.5.0。

低占用 · 高性能 · 现代化 · 本地优先的剪贴板管理工具。

经典黑白	翡翠绿	天空青

自动跟随系统深色/浅色模式，实时切换

数据管理	显示设置	快捷按键

文本悬浮预览与图片悬浮预览共用预览位置与悬浮预览延时设置（当前默认 128ms，图片与文本预览均默认开启）。

低占用 · 高性能 · 现代化 · 隐私优先

• 低占用 - 托盘常驻，主窗口默认不抢占焦点；点击外部检测与键盘导航按窗口状态处理，剪贴板记录在后台持续运行（可手动暂停）
• 高性能 - LIKE 子串搜索（支持 CJK 文本）、虚拟列表、后台图片文件写入、内容哈希去重
• 现代化 - Tauri 2 + React 19 + Tailwind CSS 4，TypeScript 与 Rust
• 隐私优先 - 历史数据默认本地存储；WebDAV 同步和在线翻译为可选功能，更新检查默认开启且可关闭
• 多语言界面 - 简体中文 / English / 繁體中文，设置中切换，多窗口实时同步

完整功能列表与术语约定见 FEATURES.md。

文件历史保存复制时的原始路径，并可能保存可用的暂存副本（staged fallback）。原文件移动或删除后，仅在暂存副本仍可用时才可回退，并非所有文件都能恢复。可见文件与缓存图片卡片统一刷新资源可用性，区分未知、检查中、可用和不可用，并分别判断剪贴板载荷是否可用。资源缺失显示“已失效”；不支持的伴生格式不会把仍存在的物理文件标成缺失，但会禁用复制/粘贴。图片加载错误只显示“预览加载失败”，不会把存在的文件误判为失效；预览大小限制也不影响存在性检查。可用性不等于实际可读取或可解码，执行时还会检查所需内容；可读取的原文件即使预览失败或伴生格式不受支持，也可另存为原始字节或在资源管理器中定位。另存为和资源管理器定位会按当前条目重新解析原始/暂存路径，而不是使用卡片中的旧路径。详见 文件管理。

复制/粘贴的卡片、菜单、键盘、全局快速/收藏/重复快捷键、合并及翻译入口共用后端执行前检查；检查失败不改写现有剪贴板或隐藏主窗口。只有后端成功才触发成功反馈和操作后的选择/排序更新；取消另存为不提示成功或错误，后续列表刷新失败则单独提示。操作错误使用本地化的安全原因，原始诊断只记入日志。粘贴成功表示剪贴板写入和按键模拟成功，不保证目标应用已接收内容。详见 操作检查与反馈。

上下选择、分类切换、Enter/Shift+Enter 和 Delete 需先在设置 → 快捷按键开启键盘导航（默认关闭）；分类切换还需显示分类筛选栏。

从 Releases 页面下载最新版本：

• 安装版（推荐）：ElegantClipboard_x.x.x_<架构>-setup.exe
• 便携版：ElegantClipboard_x.x.x_<架构>_portable.exe（无需安装，直接运行）

Release 工作流分别构建 x64 和 arm64；请选择与设备匹配的下载文件。运行界面需要 Microsoft Edge WebView2 Runtime，安装包包含其引导安装程序，便携版需已有该运行时。

WebView2 更新后，正在运行的环境可以继续使用已加载版本；版本差异、渠道后缀或更新通知不会单独触发应用重启或阻止窗口创建。仅对进程崩溃、连接断开、窗口就绪超时等真实故障进行有限次数的自动恢复。

winget install Y-ASLant.ElegantClipboard

scoop bucket add elegantclipboard https://github.com/Y-ASLant/ElegantClipboard
scoop install elegantclipboard

• Node.js 20.19+（20.x）、22.13+（22.x）或 24+，推荐当前 LTS（以依赖的 engines 要求为准）
• 当前稳定版 Rust（edition 2024）及对应 Windows MSVC 工具链
• Windows 10/11、Microsoft C++ Build Tools 与 WebView2 Runtime
• PowerShell；使用 make 命令还需安装 GNU Make

Rust 的 *-pc-windows-msvc 目标需要 MSVC x64/x86 编译与链接工具和 Windows SDK；只有 Rust、VS Code 或 WebView2 不够。若提示 link.exe not found，可用微软 Build Tools 安装器选择这两个组件，或执行：

winget install --id Microsoft.VisualStudio.2022.BuildTools --exact --source winget --override "--add Microsoft.VisualStudio.Component.VC.Tools.x86.x64 --add Microsoft.VisualStudio.Component.Windows11SDK.26100 --passive --wait --norestart"

安装需要管理员授权。安装完成后重新打开终端；若普通 PowerShell 仍未加载编译环境，从开始菜单打开 x64 Native Tools Command Prompt for VS 2022，切到项目目录后再执行构建。该环境同时配置编译器、链接器、头文件和 SDK 库路径，不要仅把某个 link.exe 文件加入 PATH。组件信息见 微软 Build Tools 文档。

# 克隆仓库
git clone https://github.com/Y-ASLant/ElegantClipboard.git
cd ElegantClipboard

# 安装依赖
npm install

# 仅构建前端静态资源（dist/）
npm run build

# 开发模式
npm run tauri dev

# 构建生产版本（默认仅当前机器架构）
npm run tauri build

# 跨架构构建前安装对应 Rust target，并准备该架构的 MSVC 编译/链接工具
rustup target add x86_64-pc-windows-msvc aarch64-pc-windows-msvc

# 分别构建 x64 / arm64 安装包（需执行两次）
npm run tauri build -- --target x86_64-pc-windows-msvc
npm run tauri build -- --target aarch64-pc-windows-msvc

# 前端类型与零警告代码检查（含测试、配置及 e2e）
npm run typecheck
npm run lint

# 完整质量门禁 / 格式修复（Makefile 使用 PowerShell）
make check
make format

# 前端、应用 Rust 和剪贴板分叉纯测试（默认 / 无默认特性）
make test
# 或分别执行：
npm test
cargo test --manifest-path src-tauri/Cargo.toml --all-targets
cargo test --manifest-path clipboard-rs/Cargo.toml --all-targets
cargo test --manifest-path clipboard-rs/Cargo.toml --all-targets --no-default-features

# 性能基准 / 前端端到端测试（单独运行）
npm run bench
npx playwright install chromium
npm run test:e2e

说明：

• npm run build 只会执行 tsc && vite build，用于前端资源构建，不会生成安装包。
• 安装包由 npm run tauri build 生成；不指定 --target 时只构建当前环境对应架构。
• 需要同时发布 x64 和 arm64 时，需分别执行两次带 --target 的构建命令（或在 CI 中分架构构建）。
• npm run typecheck 检查应用、测试、构建配置和 e2e 的 TypeScript；npm run lint 同样覆盖这些范围并以 --max-warnings=0 拒绝警告。前端构建不能替代完整类型检查。
• make check 包含前端类型/ESLint、应用及剪贴板分叉的 Rustfmt 检查、应用的 cargo check --all-targets，以及应用和分叉的 cargo clippy --all-targets -- -D warnings；分叉还执行 --no-default-features Clippy。make format 使用 cargo fmt 格式化应用与分叉，并执行前端自动修复；使用当前 Rust 工具链，不依赖写死的 rustup 工具链路径。
• make test 运行前端、应用 Rust 和剪贴板分叉默认/--no-default-features 的纯测试。分叉涉及系统剪贴板或桌面会话的测试默认忽略；仅在准备好独占剪贴板的真实桌面环境后，显式执行 cargo test --manifest-path clipboard-rs/Cargo.toml --all-targets -- --ignored --test-threads=1（会读写系统剪贴板，不属于默认质量检查）。
• npm run test:e2e 使用 Chromium、Vite 开发服务器及明确的 Tauri IPC 测试夹具运行实际前端应用，检查待完成/拒绝/取消操作与反馈；不靠过滤“缺少 Tauri”错误通过。它不启动原生桌面，不验证真实剪贴板、系统对话框、全局钩子、目标应用接收粘贴或其他平台运行效果；这些需要单独的原生桌面验证。

本次准备发布 v1.2.10。仓库保留 0.0.0 开发占位版本，正式构建由 Release workflow 从标签注入版本号。若需要本地安装包显示 1.2.10，先执行：

# 修改 package.json、tauri.conf.json 和 Cargo.toml 的应用版本
.\scripts\bump-version.ps1 1.2.10

脚本只修改这三个文件。若提交手动升版的改动，还需同步 package-lock.json 的顶层与根项目版本，以及 src-tauri/Cargo.lock 中 elegant-clipboard 的版本；不要修改依赖版本。

确认要发布的改动已提交后，推送标签触发 x64 / arm64 构建：

git tag v1.2.10
git push origin v1.2.10

发布前执行 make check、make test、make build，并在原生 Windows 桌面验证复制/粘贴、两种粘贴按键、失效文件复查、另存为取消与从 v1.2.9 升级；使用 Makefile 时可指定 make SHELL=pwsh check 等命令，以 PowerShell 7 执行。不要把开发占位版本的包作为正式包上传。

本版还需验证 WebView2 更新场景：

• 在 beta / dev / canary 渠道运行时及已加载版本与可用版本不同的情况下，设置、翻译、图片/文本预览和编辑窗口仍可打开。
• 运行时更新后持续运行超过十分钟，确认没有仅因版本变化或更新事件而重启、弹恢复通知或熔断。
• 在隔离的测试会话中验证真实进程故障或连接断开仍触发恢复，连续失败最多自动恢复两次；正常运行后的成功版本检查可以清理旧恢复计数。

这些项目是发版前的验收要求，单元测试与浏览器 E2E 不能替代真实 Windows 桌面验收。

工作流创建的是 Release 草稿，正文不会自动读取更新日志。待 x64 / arm64 安装版和便携版四个产物齐全后，将 v1.2.10 更新日志中的本版内容填入草稿，核对版本与产物，完成验收后再发布，并把日志中的「待发布」改为实际发布日期、比较链接固定为 v1.2.9...v1.2.10。Scoop 清单在正式发布后按实际产物哈希更新。GPUI 2.0 是独立分支，本次 v1.2.10 继续使用 Tauri + React 1.x。

默认数据目录为可执行文件所在目录；可在设置 → 数据管理 → 数据存储位置选择其他目录，迁移或路径切换后重启生效。

安装版采用当前用户安装模式；是否需要管理员写入权限取决于所选目录的 Windows 权限，并非安装版一律需要管理员。便携模式通过 exe 同级目录是否存在 uninstall.exe 判断。安装版和便携版均需保证配置文件所在目录及所选数据目录可写。

ZIP 备份与数据迁移包含数据库和应用托管的图片、图标、暂存文件；普通文件历史中的原始路径不会因此变成完整文件备份。

MIT License