LocalSend 完整指南：跨平台安全文件分享、局域网配置与源码构建

LocalSend 是一款免费、开源的跨平台应用，让你可以在本地网络中通过 HTTPS 加密安全地向附近的设备分享文件和消息，全程无需互联网连接。本文基于项目的西班牙语官方文档 support/readme/README_ES.md，完整覆盖其下载渠道、平台兼容性、防火墙与路由器配置、便携式模式、隐藏启动等实操要点，并结合仓库中 Rust 核心包的源码，深入解析 53317 端口的组播发现机制与“每个设备自动生成自签名 TLS 证书”的安全模型，最后给出从源码构建、参与翻译贡献与常见故障排查的可复制步骤。

项目定位：不依赖互联网的 REST API + HTTPS 安全通信

官方文档对 LocalSend 的定义是：它是一款跨平台应用，设备之间通过 REST API 通信，并使用 HTTPS 加密传输所有数据。与其他依赖外部服务器的消息应用不同，LocalSend 不需要互联网连接，也不涉及任何第三方服务器——这使它成为本地通信场景中快速且可靠的方案。

从源码结构看，这一承诺由仓库中的 Rust 核心包 packages/core 支撑：

• 设备发现：packages/core/src/discovery/mod.rs 定义了组播加入、接口过滤、注册超时等完整的发现配置；
• 加密身份：packages/core/src/crypto/cert.rs 中每个设备在运行时生成自己的密钥对与自签名证书，无需任何中心化 CA；
• 网络传输：packages/core/src/http 下分 client/server 两侧实现本地 HTTP(S) 服务；
• Flutter 应用层：app/lib 中的 provider 层（如 app/lib/provider/network）调用 packages/localsend_isolates 里的 Rust 桥接代码执行实际的发现与传输任务。

仓库根目录的 support/docs/dependency-hierarchy.svg 提供了整个依赖层次结构图，适合想快速理解模块边界的读者。

下载渠道与平台兼容性

官方建议优先从应用商店或包管理器安装，因为应用本身没有自动更新功能。各平台的分发渠道如下（来自 README.md 与西班牙语文档一致的渠道表）：

Windows	macOS	Linux	Android	iOS	Fire OS
Winget	App Store	Flathub	Play Store	App Store	Amazon
Scoop	Homebrew	Nixpkgs	F-Droid
Chocolatey	DMG 安装器	Snap	APK
EXE 安装器		AUR
便携版 ZIP		TAR
		DEB
		AppImage

各发行版打包情况的持续跟踪见仓库中的 CI 工作流 .github/workflows/ci.yml 与一系列发布构建工作流（如 build_appimage.yml、build_cli_linux.yml）。

最低版本兼容性（原文档表格完整保留）：

平台	最低版本	备注
Android	5.0	-
iOS	12.0	-
macOS	11 Big Sur	更老系统可尝试 OpenCore Legacy Patcher 2.0.2（见上游 issue #1005 讨论）
Windows	10	最后一个支持 Windows 7 的版本是 v1.15.4，未来可能有更新版本的回移
Linux	N.A.	-

网络配置：防火墙端口与路由器 AP 隔离

绝大多数情况下 LocalSend 可以开箱即用。但如果收发文件失败，最常见的原因是防火墙或路由器设置。官方文档给出的防火墙规则是：

流量类型	协议	端口	操作
入站（Incoming）	TCP, UDP	53317	允许
出站（Outgoing）	TCP, UDP	任意	允许

为什么是 53317？ 这个端口在核心包中是编译期常量：packages/core/src/multicast/mod.rs 定义了 DEFAULT_PORT = 53317，同时定义了 IPv4 组播组 224.0.0.167（L28）与对应的 IPv6 组播组。测试用例（如 packages/core/src/http/client/url.rs）也反复以 53317 构造 https://192.168.1.1:53317/api/localsend/v2/register 这类注册 URL 进行断言，证明该端口贯穿“组播发现 + HTTPS 注册”整条链路。

组播发现的关键参数同样可以在 packages/core/src/discovery/mod.rs 中核实：

• DEFAULT_DISCOVERY_TIMEOUT = 500ms（L26）：每个注册请求的超时上限，因为局域网内的对等方要么很快响应要么根本不响应，短超时可避免无响应主机拖慢扫描；
• SCAN_CONCURRENCY = 50（L33）：子网扫描时并发探测的主机数；
• DiscoveryConfig 结构体支持按网络接口过滤（interface_filter），并携带设备信息与 TLS 身份。

路由器设置：务必确认路由器的 AP 隔离（AP-Isolation）已关闭。它通常默认关闭，但部分路由器（尤其是访客网络）可能开启；开启后设备之间的连接会被直接禁止，这是“设备不可见”问题最常见的根因。

进阶配置：便携式模式与隐藏启动

这两项来自西班牙语文档“Configuración”一节，是桌面端用户的高频需求：

便携式模式（Portable Mode）（v1.13.0 引入）：

在可执行文件所在目录创建一个名为 settings.json 的文件（可以为空文件）。应用检测到该文件后，会把它作为配置存储位置，取代系统默认位置。这对把 LocalSend 放在 U 盘/便携目录中使用的场景非常有用——配置随目录走，不污染系统设置目录。

隐藏启动（Start hidden）（v1.15.0 更新）：

localsend_app.exe --hidden

应用启动后不会弹出窗口，仅驻留在系统托盘。注意版本差异：在 v1.14.0 及更早版本中，应用“启动隐藏”的行为取决于 autostart 参数与隐藏选项的组合，而非独立的 --hidden 参数。

工作原理：每台设备自动生成自签名 TLS 证书

文档表述为：“LocalSend 使用安全的通信协议，设备间通过 REST API 通信；所有数据通过 HTTPS 安全传输，TLS/SSL 证书在每台设备上自动生成，确保最高安全。”

从源码看，这句话的落点在 packages/core/src/crypto/cert.rs：

• generate_self_signed()（L32）生成 RSA-2048 密钥对与自签名证书，返回包含证书 PEM、私钥 PEM 与指纹的 SelfSignedCert；
• verify_cert_from_pem() / verify_cert_from_der() 用于对端校验对方出示的证书与公钥是否自洽；
• fingerprint_from_cert_der() 生成设备指纹——也就是界面上用于区分设备的“指纹”标识。

在发现阶段，packages/core/src/discovery/mod.rs 的 DeviceIdentity（证书 PEM + 私钥 PEM）作为客户端证书随每个 register 请求发送——注释明确写道“HTTPS 模式下客户端证书是强制的”。也就是说，连接建立即完成双向 TLS 认证，不依赖任何预置 CA 或云端服务，这正是“无需互联网也能安全”的实现基础。

更完整的协议细节（如 v2 API 的 register/info 端点语义）见上游独立的 protocol 文档仓库，本文不展开。

从源码构建（Primeros Pasos）

文档给出的最小构建流程：

1. 安装 Flutter——直接安装，或用 fvm 管理版本（所需版本见 .fvmrc）；
2. 安装 Rust（工具链版本锁定在 rust-toolchain.toml，当前为 1.97.1，并启用 clippy 组件）；
3. 克隆 LocalSend 仓库；
4. cd app 进入应用目录；
5. flutter pub get 下载依赖；
6. flutter run 启动应用。

原文档的重要注意事项（完整保留）：LocalSend 目前要求的 Flutter 版本较旧（以 .fvmrc 为准，当前锁定为 3.41.9，与 CI 工作流 .github/workflows/ci.yml 中 FLUTTER_VERSION: "3.41.9" 一致）。如果系统级安装的 Flutter 版本与之不一致，可能引发构建问题。为保证开发环境一致性，项目推荐使用 fvm 管理版本：安装 fvm 后，把命令中的 flutter 全部替换为 fvm flutter。

补充一点：CONTRIBUTING.md 的 Run 小节指出，完整参与开发时还应执行 dart run build_runner build -d 来生成代码（包括国际化生成文件 app/lib/gen），再运行应用。

参与贡献：翻译与缺陷修复

翻译：官方推荐通过 Weblate 平台管理翻译；也可以 fork 仓库手动添加。翻译源文件位于 app/assets/i18n 目录，编辑 _missing_translations_<locale>.json（缺失词条清单）或 strings_<locale>.i18n.json 来新增/更新翻译。以西班牙语为例，_missing_translations_es_ES.json 顶部的 @@info 字段提示：编辑后可运行 dart run slang apply --locale=es-ES 快速应用新增翻译。

原文档的重要提示（完整保留）：以 @ 装饰的字段（如 @@info）不是翻译对象，它们在应用中完全不使用，仅是关于文件本身或给译者提供上下文的说明性文本。

翻译完成后，app/lib/gen 目录下会为每个语言生成对应的 strings_<locale>.g.dart 访问器文件（如 strings_es_ES.g.dart），应用运行时即通过这些生成文件访问译文。

缺陷修复与改进（原文档规则保留）：

• Bug 修复：发现问题后，创建附带清晰问题描述与修复方案的 pull request；
• 功能改进：先创建 issue 讨论改进的必要性，再动手实现。

更多规范见 CONTRIBUTING.md。

故障排查

原文档的排查表完整保留如下，覆盖了绝大多数“设备不可见/速度过慢”场景：

问题	发送方平台	接收方平台	解决方案
设备不可见	任意	任意	确认路由器上已关闭 AP-Isolation；开启后设备间连接会被禁止
设备不可见	任意	Windows	将网络配置为“专用（private）”网络；Windows 对“公用”网络限制更严格
设备不可见	macOS、iOS	任意	尝试在系统设置的“隐私”一栏中切换“本地网络”权限
速度过慢	任意	任意	使用 5 GHz 频段；在两台设备上同时关闭加密
速度过慢	任意	Android	已知问题（上游 saf_stream 插件的 issue #4）

结合前文的原理可以这样理解这些解法：设备不可见的三个解法分别对应组播发现链路上的三类阻塞点——路由器层面（AP 隔离）、系统网络策略层面（Windows 防火墙/网络类型）、操作系统权限层面（macOS/iOS 的本地网络权限）；而“速度过慢”的解法则对应无线电频段与 HTTPS 加解开销两条路径——组播发现默认使用 UDP/53317，而传输走 HTTPS，关闭加密可排除 TLS 处理带来的吞吐下降。

小结

LocalSend 的技术方案可以概括为三句话：UDP 组播（组 224.0.0.167 / 端口 53317）发现邻居，HTTPS + 每设备自生成 RSA-2048 自签名证书完成双向认证，REST API 传输数据。文档中的防火墙表、AP 隔离提示、便携模式与 --hidden 参数都是围绕这条链路展开的实操配置；构建侧只需锁定 Flutter 3.41.9（fvm 管理）+ Rust 1.97.1 即可从源码运行。翻译、缺陷修复的贡献入口也都已给出明确文件路径，读者可直接从 app/assets/i18n 或 CONTRIBUTING.md 继续深入。