Magic Wormhole：安全地从一台计算机把东西送到另一台计算机 #

Magic Wormhole 是什么？ #

Magic Wormhole 是一款开源的安全文件传输工具，其官方口号是 "get things from one computer to another, safely"（安全地把东西从一台计算机送到另一台）。它同时提供一个 Python 库和一个名为 wormhole 的命令行工具，用户可以在两台计算机之间传输任意大小的文件、整个目录，或者一小段文本。

它的核心机制是"wormhole 代码"：发送方生成并显示一个简短、可发音的代码（基于音标上易于区分的词表），接收方只需在另一端输入同一代码，两端即可建立加密通道完成传输。整个过程无需注册账号、无需共享 IP、无需提前配置，特别适合在不同网络环境之间快速、私密地传送文件。

Magic Wormhole 采用 MIT 许可证发布（本仓库对应版本，对应 v3 代码），兼容 Python 3.10 及以上版本（官方测试至 3.12）。它在 GitHub 上拥有约 23k Star、759 Fork，是开发者社区中广泛使用的传输工具之一。

Magic Wormhole 有哪些亮点特色？ #

• 简短易记的 wormhole 代码：代码使用音标上区分度高的词表生成，简短且可发音；接收端支持 Tab 补全，通常只需输入几个字符即可完成配对。
• 代码一次性使用：每次传输的 wormhole 代码仅使用一次，传输完成后即失效，无需记忆、也不存在被重复利用的风险。
• 端到端加密传输：两端通过约定的代码协商出加密密钥（基于 SPAKE2 等协议），数据在传输过程中保持加密，降低被第三方窃听的可能。
• 支持任意大小的文件与目录：既可发送单个文件、整个目录，也可发送一小段文本，满足从快速分享到批量传输的不同需求。
• 跨平台支持：可在 Windows、macOS 和 Linux 上运行，许多操作系统已内置或可通过包管理器直接安装（如 apt、brew 等）。
• 开源且免费：项目以 MIT 许可证发布，源码公开，任何人都可以审阅、修改或自行部署，无需付费授权。
• 依赖成熟的传输服务：程序使用 mailbox 服务器（用于交换代码与连接信息）和 transit relay（用于中继数据）两个独立服务，二者均为开源项目，可自行搭建。
• 提供库与命令行双重形态：既可作为命令行工具开箱即用，也可作为 Python 库集成到其他应用或脚本中。

免费下载 Magic Wormhole #

以下为官方提供的 Windows 可执行文件安装包，点击链接即可下载。

提示：其他平台（macOS、Linux）的官方安装方式请见下方"如何安装"章节，或访问 官方文档 获取最新的安装说明。

Magic Wormhole 如何使用？ #

Magic Wormhole 的日常使用主要围绕 wormhole send 和 wormhole receive 两条命令展开，操作十分简单：

1. 在发送端发起传输：在发送方计算机上打开终端，执行 wormhole send 文件名（或 wormhole send 目录名），程序会生成并显示一个简短的 wormhole 代码，例如 4-purple-sausages。
2. 在接收端输入代码：在接收方计算机上执行 wormhole receive，按提示输入发送端显示的代码；也可直接执行 wormhole receive 4-purple-sausages 一步完成。
3. 等待通道建立并传输：两端代码匹配后，程序会自动协商加密连接并开始传输；传输过程中会显示进度条。
4. 接收文件落盘：接收端会选择当前目录作为保存位置（也可指定路径），传输完成后文件即出现在本地。
5. 发送文本（可选）：如果只想发送一小段文字，可以使用 wormhole send --text "要发送的内容"，接收端同样通过代码接收即可。

对于偏好图形界面的用户，社区也提供了若干第三方 GUI 客户端（如 macOS 上的相关封装），可在官方文档或社区资源中查找。

Magic Wormhole 的常见问题？ #

wormhole 代码是如何工作的？ 发送端会生成一个基于词表的短代码，并把代码对应的"名称"注册到 mailbox 服务器；接收端输入同一代码后，两端在服务器上完成会合，再协商建立加密连接。代码在服务器上只是资源标识，不承载实际的加密密钥。

Magic Wormhole 是否安全？ 是的。两端通过在代码中隐含的信息协商出加密密钥，真实文件内容在传输过程中保持加密。代码是一次性的，且不会暴露文件的真实内容。但请注意，不要通过不安全的渠道泄露 wormhole 代码，否则任何人拿到代码都可能接收文件。

文件大小有没有限制？ 官方并未给出硬性的大小限制，理论上可以传输任意大小的文件甚至整个目录。实际速度取决于两端网络带宽以及 transit relay 的中继情况。

使用 Magic Wormhole 需要安装 Python 吗？ 作为 Python 工具，常规安装方式（如 pip install magic-wormhole）需要 Python 3.10 及以上环境。不过许多操作系统已将其打包为原生软件包（如 apt、brew），这些渠道安装时无需手动配置 Python。Windows 用户也可直接使用本项目提供的 wormhole.exe 可执行文件。

为什么传输速度有时较慢？ 当两端无法建立直接连接时，数据会通过 transit relay 中继转发，速度受中继服务器带宽影响。若两端处于同一局域网且 NAT 穿透成功，速度通常会更快。

遇到连接失败或传输中断怎么办？ 可以检查网络是否允许与 mailbox 服务器和 transit relay 通信；若处于企业防火墙或代理环境中，可能需要放行相应端口。必要时可参考官方文档或查阅 GitHub Issues 获取针对性的排查方法（参考社区常见反馈）。

Magic Wormhole 如何安装？ #

Magic Wormhole 在多个操作系统的官方软件源中已收录，推荐优先使用系统包管理器安装。

Windows

1. 最简单的方式是直接下载本页面提供的 wormhole.exe 可执行文件，双击即可运行（无需额外安装）。
2. 也可以通过 Python 安装：先安装 Python 3.10 或更高版本，然后在命令行执行 pip install magic-wormhole。
3. 需要 pywin32 作为 Windows 平台依赖，通常会自动一并安装。

macOS

1. 使用 Homebrew：执行 brew install magic-wormhole。
2. 或者通过 pip：执行 pip install magic-wormhole。
3. 安装完成后在终端运行 wormhole --version 验证。

Linux

1. Debian / Ubuntu 系列：sudo apt install magic-wormhole。
2. Fedora / RHEL 系列：使用对应的 dnf/yum 包名安装（具体包名以发行版仓库为准）。
3. 通用方式：pip install magic-wormhole（需 Python 3.10+）。

从源码安装（可选）

1. 克隆仓库：git clone https://github.com/magic-wormhole/magic-wormhole。
2. 进入目录后执行 pip install . 进行安装。
3. 开发调试时可使用 pip install -e . 以可编辑模式安装。

说明：由于官方不再发布最新独立可执行文件版本，若希望使用最新功能，建议优先采用 pip 或系统包管理器安装方式。

Magic Wormhole 如何卸载？ #

Windows

1. 如果使用的是 wormhole.exe 单文件，直接删除该文件即可，无需卸载程序。
2. 如果是通过 pip 安装，打开命令行执行 pip uninstall magic-wormhole。
3. 如需清理残留，可检查 %APPDATA% 或用户目录下是否存在相关配置缓存并手动删除。

macOS

1. 使用 Homebrew 安装的，执行 brew uninstall magic-wormhole。
2. 使用 pip 安装的，执行 pip uninstall magic-wormhole。
3. 如需清理残留，可检查 ~/Library/Application Support 及 ~/.config 下是否有相关目录。

Linux

1. 使用 apt 安装的，执行 sudo apt remove magic-wormhole（如需彻底清理可加 --purge）。
2. 使用 pip 安装的，执行 pip uninstall magic-wormhole。
3. 配置文件通常位于 ~/.config/wormhole/ 等用户目录下，可按需手动删除。

提示：上述卸载步骤基于通用安装方式整理，具体路径与命令可能因系统版本或安装渠道略有差异。卸载前建议确认当前没有正在进行的传输任务，以免中断数据。