EcoPaste Documentation

1. Project Overview & Quickstart (EcoPasteHub/EcoPaste) Copy Chapter

About Copy Chapter

EcoPaste is an open-source desktop clipboard manager built with a Rust-first Tauri architecture: durable behavior lives in Rust, while the React frontend focuses on rendering and interaction.

The app is designed to be fast, lightweight, and maintainable, with local storage, SQLite search, native shortcuts, tray integration, backup support, and a focused cross-platform surface for macOS and Windows.

Features Copy Chapter

• Capture clipboard history for plain text, HTML, RTF, images, files, and folders.
• Search clipboard content and notes with SQLite FTS5.
• Filter history by source application and content type.
• Protect sensitive content by skipping high-confidence secrets such as private keys, service tokens, AWS keys, and JWTs.
• Preview text, images, and files in a dedicated preview window.
• Paste, copy, copy as plain text, reveal files, open links, add notes, pin, favorite, delete, and drag items out to other apps.
• Organize history with favorites, pinned items, notes, custom groups, and configurable item actions.
• Tune capture order, size limits, retention, display density, list sorting, and window behavior.
• Export and import .ecopastebak backups, including encrypted backup containers.
• Keep clipboard data, resources, and settings local to your machine.

Contributing Copy Chapter

Development setup, architecture notes, quality checks, and contribution
expectations live in the contribution guide.

License Copy Chapter

EcoPaste is licensed under the Apache License 2.0.

2. Official Technical Reference & Guides (EcoPasteHub/EcoPaste-docs) Copy Chapter

File: docs/community/index.mdx Copy Chapter

社区交流

🎉 欢迎加入 EcoPaste 社区交流群！这里是大家交流经验、分享点滴的小天地，期待你的加入，一起畅所欲言～

⚠️ 温馨提示：群聊仅限日常讨论和经验分享，如需反馈问题或提交新需求，请按以下步骤操作：

1. 🔍 优先查阅常见问题或浏览已有 issues。

2. ❓ 如果问题仍未解决，请提交新的 issue，并附上详细描述，方便我们快速定位和解决。

File: docs/guide/install.mdx Copy Chapter

安装指南

Windows Copy Chapter

手动安装 Copy Section

• 32 位操作系统请下载 *_x86-setup.exe 并进行安装。
• 64 位操作系统请下载 *_x64-setup.exe 并进行安装。
• ARM64 架构请下载 *_arm64-setup.exe 并进行安装。

MacOS Copy Chapter

:::warning EcoPaste.app 已损坏，无法打开。
点击此处查看解决方案。
:::

手动安装 Copy Section

• Apple Silicon 芯片请下载 *_aarch64.dmg 并进行安装。
• Intel 芯片请下载 *_x64.dmg 并进行安装。

使用 Homebrew 安装 Copy Section

1. 添加我们的 tap 源：

brew tap EcoPasteHub/EcoPaste

2. 安装：

brew install ecopaste

3. 更新：

brew upgrade ecopaste

4. 卸载：

brew uninstall --cask ecopaste

brew untap EcoPasteHub/EcoPaste

Linux Copy Chapter

仅支持在X11环境下使用

Ubuntu、Debain 系列 Copy Section

1.安装

前往下载页面下载 deb 文件，然后执行以下命令：

# 安装依赖
sudo apt update
sudo apt install libwebkit2gtk-4.0-dev libgtk-3-dev

sudo dpkg -i ecopaste.deb

2.更新

前往下载页面下载 最新的deb 文件

sudo dpkg -i ecopaste.deb

3.卸载

sudo apt-get purge ecopaste

ArchLinux、Manjaro 系列 Copy Section

1.安装

yay -S eco-paste-bin

2.更新

yay -Syyu

3.卸载

sudo pacman -Rcns eco-paste-bin

Red Hat、CentOS、Fedora 系列 Copy Section

前往下载页面下载 rpm 文件，然后执行以下命令：

1.安装

# 安装依赖
sudo dnf check-update
sudo dnf install webkit2gtk4.0-devel libappindicator-gtk3-devel

rpm -ivh ecopaste.rpm

2.更新

前往下载页面下载 新版本rpm 文件

rpm -Uvh ecopaste.rpm

3.卸载

rpm -ev ecopaste

其他发行版 Copy Section

1.安装

前往下载页面下载 Appimage 文件，然后执行以下命令：

chmod +x ecopaste.AppImage
./ecopaste.AppImage

2.创建桌面图标

以上步骤已经打开了ecopaste,可以正常使用，但缺少桌面图标，且终端不能关闭，以下步骤可以创建桌面图标

./ecopaste.AppImage --appimage-extract
sed -i 's|Exec=.*|Exec=/opt/ecopaste/EcoPaste.AppImage|g' squashfs-root/usr/share/applications/eco-paste.desktop
sed -i 's/^Icon=.*/Icon=EcoPaste/g' squashfs-root/usr/share/applications/eco-paste.desktop
install -Dm644 squashfs-root/usr/share/applications/eco-paste.desktop /usr/share/applications/EcoPaste.desktop
wget "https://raw.githubusercontent.com/EcoPasteHub/EcoPaste-Logo/refs/heads/master/img/logo.svg" -O EcoPaste.svg
install -Dm644 EcoPaste.svg /usr/share/icons/hicolor/scalable/apps/EcoPaste.svg
rm -r squashfs-root EcoPaste.svg
mkdir -p /opt/ecopaste
mv ecopaste.AppImage /opt/ecopaste/

3.更新

前往下载页面下载新版本Appimage 文件，替换之前下载的文件

mv ecopaste.AppImage /opt/ecopaste/

4.卸载

rm -r /opt/ecopaste
rm /usr/share/applications/EcoPaste.desktop /usr/share/icons/hicolor/scalable/apps/EcoPaste.svg

File: docs/problem/linux/paste-failure.mdx Copy Chapter

粘贴功能偶尔失效

原因 Copy Chapter

在 Linux 上，系统默认不允许应用程序抢占光标焦点，这可能会导致粘贴功能表现不佳。

解决方案 Copy Chapter

将阻止焦点抢占的级别设置为低。

KDE 桌面环境 Copy Section

1. 打开 系统设置。
2. 进入 窗口管理 > 窗口行为。
3. 找到 阻止焦点抢占，将其设置为 低。

File: docs/problem/linux/start-failed.mdx Copy Chapter

应用启动失败

原因 Copy Chapter

EcoPaste 依赖 WebKitGTK，如果缺少必要的依赖项，会导致启动失败。

解决方案 Copy Chapter

请确保已安装所需的依赖项。

ArchLinux / Manjaro Copy Section

sudo pacman -S webkit2gtk-4.1

Debian / Ubuntu Copy Section

sudo apt-get install libwebkit2gtk-4.0-dev

Gentoo Copy Section

sudo emerge --ask net-libs/webkit-gtk:4.1

File: docs/problem/macos/authorization.mdx Copy Chapter

更新 EcoPaste 需要重新授权

原因 Copy Chapter

和应用已损坏的问题一样，也是由于缺少应用签名导致的，为什么不对应用签名？点击此处查看原因。

授权步骤 Copy Chapter

辅助功能访问权限 Copy Section

首次安装授权

重新安装授权

1. 参考首次安装授权，根据 ① 和 ② 打开系统设置。

2. 如下图操作：

3. 重复首次安装授权步骤。

完全磁盘访问权限 Copy Section

File: docs/problem/macos/damage.mdx Copy Chapter

EcoPaste.app 已损坏，无法打开

报错截图 Copy Chapter

报错原因 Copy Chapter

由于应用需要官方签名，才能避免安装后弹出“应用已损坏”的提示，但官方签名的费用昂贵（每年 99 美元），开源项目无法负担。因此，需要手动绕过签名以正常使用 EcoPaste。

解决方案 Copy Chapter

在终端窗口输入以下命令，按回车键后输入系统密码（不可见）并再次按回车键即可。

sudo xattr -r -d com.apple.quarantine /Applications/EcoPaste.app

File: docs/problem/windows/paste-failure.mdx Copy Chapter

部分应用粘贴失效

原因 Copy Chapter

当目标应用以管理员权限启动时，粘贴操作可能会失效。

解决方案 Copy Chapter

确保 EcoPaste 也以管理员权限启动，这样可以避免权限冲突导致粘贴失效。