LocalSend：跨平台离线文件传输的技术指南——从防火墙配置、桌面高级用法到发现协议与源码构建

LocalSend 是一款不依赖互联网、仅通过局域网在邻近设备之间安全共享文件与消息的免费开源应用。本篇以项目官方土耳其语 README（support/readme/README_TR.md）为主体，完整覆盖其安装渠道与平台兼容性、防火墙规则、便携模式与 --hidden 隐藏启动等桌面高级用法、协议工作原理以及从源码构建的完整步骤；并结合仓库源码补充了默认端口、自签名证书、设备发现等底层实现证据，帮助读者既能按文档上手使用，也能理解其技术构成并参与贡献。

一、关于 LocalSend

LocalSend 是一款多平台应用，设备间通过 REST API 通信，并全程使用 HTTPS 加密。与其他依赖外部中转服务器的即时通讯/共享应用不同，LocalSend 不需要互联网连接，也不接触任何第三方服务器——数据只在你自己的局域网内流动。这使它成为一个快速且可信的本地通信方案，典型场景包括：

• 手机与电脑之间互传照片、文档，无需云盘或数据线；
• 在无外网环境（如机房、内网、飞行模式）下传输文件；
• 替代系统自带的 AirDrop 等封闭传输方案，实现 Android、iOS、Windows、macOS、Linux 全平台互通。

关于协议的更完整定义可参考 LocalSend Protocol 官方文档（项目以独立的 protocol 仓库维护协议规范）。

二、平台支持与分发渠道

由于应用本身没有内置自动更新能力，官方建议从应用商店或包管理器安装，以便获得持续更新。各平台可用的官方分发渠道如下（以 support/readme/README_TR.md 与 CONTRIBUTING.md 中 Distribution 一节为准）：

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

兼容性（最低系统版本）

平台	最低版本	备注
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，之后版本可能出现针对 Win7 的 backport
Linux	N.A.	-

三、安装后的网络配置：防火墙与 AP 隔离

大多数情况下 LocalSend 开箱即用，但如果收/发文件失败，通常是本地网络拦截了流量。需要放行以下规则：

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

从源码结构看，53317 是项目的硬编码默认端口：Rust 核心与 CLI 的 默认端口常量（const DEFAULT_PORT: u16 = 53317）均指向它，CLI 的 main.rs 也注明 HTTP 服务端口“默认取 config.toml，否则为 53317”。因此防火墙规则只需针对 53317 即可覆盖收发两端。

另一个常见坑是路由器开启了 AP 隔离（AP-Isolation / 客户端隔离）：该特性会阻断同一网段内客户端之间的通信。它默认通常关闭，但部分路由器（尤其是访客网络）会默认开启，发现设备互相“看不见”时建议首先检查。

四、桌面端高级用法：便携模式与隐藏启动

4.1 便携模式（v1.13.0 引入）

在可执行文件所在目录创建一个名为 settings.json 的文件（内容可以为空），应用便会把设置保存到这个文件而不是系统默认位置。这使得整个目录可以整体拷贝到 U 盘随身携带。

这一行为的实现位于 shared_preferences_portable.dart：SharedPreferencesPortable 是一个自定义的 SharedPreferences 存储实现，其配置路径由 buildSettingsPath 计算——优先取 Platform.resolvedExecutable 所在目录，无法解析时回退到当前工作目录，最终固定命名为 settings.json。值得注意的是 _resolveExecutable 对虚拟磁盘（如 ImDisk RAM 盘）读取可执行路径会抛 TypeError 的情况做了容错处理，说明该模式在真实 Windows 环境中有过踩坑与加固。

4.2 隐藏启动（v1.15.0 更新）

希望应用仅驻留系统托盘而不弹出主窗口时，使用 --hidden 参数启动：

localsend_app.exe --hidden

在 v1.14.0 及更早版本中，隐藏启动的判定条件是“设置了 autostart 且开启了隐藏设置”；v1.15.0 起改为直接监听 --hidden 命令行参数，行为更直观。源码侧可以看到完整的三平台落地：

• 参数常量定义在 autostart_helper.dart：const startHiddenFlag = '--hidden'；
• Windows 自启动项写入注册表 Software\Microsoft\Windows\CurrentVersion\Run，值中按需拼接 --hidden（见 autostart_helper.dart）；
• Linux 写入 ~/.config/autostart/<app>.desktop 的 Exec 行（autostart_helper.dart），启动入口 my_application.cc 会遍历 Dart 入口参数确认 --hidden 并决定是否初始隐藏窗口；
• macOS 通过 launch-at-login API 的“最小化启动”开关实现（autostart_helper.dart）。

五、工作原理：HTTPS、自签名证书与设备发现

官方文档对“如何工作”的表述是：LocalSend 使用一套安全通信协议让设备互联，交互通过 REST API 完成；所有数据经 HTTPS 传输，每台设备会即时生成自己的 TLS/SSL 证书以保证最大安全性。

仓库源码印证了这些表述的具体形态：

1. 设备身份即证书指纹。 核心库的 cert.rs 生成 RSA-2048 自签名证书（CN=LocalSend User，不设 SAN），并计算证书 DER 的 SHA-256 指纹作为设备标识——对端之间完全靠指纹互相识别，所以证书里的主机名不携带任何信息。验证逻辑（verify_cert_from_cert）会检查签名、时间有效性与（可选）公钥匹配。
2. 发现阶段走多播 + 子网扫描。 discovery/mod.rs 定义了发现参数：注册请求默认 500ms 超时（局域网对等体要么秒回要么不回应，保持短超时可避免无响应主机拖慢扫描），子网扫描并发度 50，与 Flutter 端的历史 HTTP 发现行为保持一致。发现确认成功后，设备会以 Discovered / Updated 事件（DiscoveryEvent）对外广播状态变化。
3. 注册即双向证书校验。 HTTPS 模式下客户端证书是强制的：每台设备把自己的 TLS 身份（证书 + 私钥，见 DeviceIdentity）随注册请求发送，对端据此完成身份确认。

这些机制共同解释了前文的网络配置要求：53317 端口承载 HTTPS 数据传输，而发现阶段则依赖多播/广播流量，两者都可能被防火墙或 AP 隔离阻断。

六、从源码构建（Başlarken）

官方给出的构建步骤如下，适用于想跑最新代码或贡献补丁的开发者：

1. 安装 Flutter。注意 LocalSend 目前要求特定（较旧/固定）的 Flutter 版本，所需版本见 .fvmrc；建议直接通过 fvm 管理版本；
2. 安装 Rust（当前仓库 rust-toolchain.toml 锁定工具链为 1.97.1，并附带 clippy 组件）；
3. 克隆 LocalSend 仓库；
4. cd app 进入应用目录；
5. 运行 flutter pub get 下载依赖；
6. 运行 flutter run 启动应用。

官方提示（重要）：LocalSend 目前要求较旧的 Flutter 版本，如果系统全局安装的 Flutter 与项目所需版本不一致，可能导致构建问题。为使开发环境一致，项目使用 fvm 管理 Flutter 版本——当前 .fvmrc 中固定为 flutter: 3.41.9。安装 fvm 后，请一律用 fvm flutter 替代 flutter 命令执行后续步骤。

技术栈上，应用 UI 层是 Flutter（app/），网络/协议核心是 Rust 工作区（packages/core 与 packages/localsend_isolates），通过 flutter_rust_bridge 在 isolate 中调用原生能力，另有独立的 Rust CLI 与 server 组件。

七、参与贡献：翻译与问题反馈

7.1 翻译

LocalSend 支持数十种语言。推荐的参与方式是通过 Weblate 平台管理翻译；也可以 fork 仓库后手动提交翻译文件。翻译资源位于 app/assets/i18n 目录：

• 各语言的主翻译文件（如 tr.json），当前仓库中以 <locale>.json 命名；
• 缺失词条清单 _missing_translations_<locale>.json（例如 _missing_translations_tr.json），其头部 @@info 说明补全后可运行 dart run slang apply --locale=tr 快速应用新增翻译；
• 对应的生成产物在 app/lib/gen（strings_<locale>.g.dart，由 slang 生成）。

注意：以 @@ 开头的字段不是待翻译内容，它们是仅供文件说明或给译者提供上下文的信息性文本，应用运行时不会使用。

7.2 缺陷修复与改进

• 缺陷修复：发现问题后，请提交附带清晰问题描述与修复方式的 PR；
• 改进建议：请先开 issue 讨论该改进的必要性，再动手实现。

完整的贡献流程、分发渠道打包方式见 CONTRIBUTING.md。

八、故障排除速查表

官方文档给出的排障矩阵如下，建议按“发送端/接收端平台”定位对应行：

问题	平台（发送方）	平台（接收方）	解决方案
设备不可见	任意平台	任意平台	确认路由器上已关闭 AP 隔离；开启时设备间通信会被阻断
设备不可见	任意平台	Windows	把网络类型设置为“专用”（Private）；“公用”网络下 Windows 限制更多
设备不可见	macOS / iOS	任意平台	到系统设置“隐私”中的“本地网络”权限，尝试关闭再打开该开关
速度太慢	任意平台	任意平台	改用 5GHz 频段；两台设备都临时关闭加密以排除瓶颈
速度太慢	任意平台	Android	已知问题（Flutter 侧 SAF 流读取限制所致），属上游已知项

实践建议：排障时先用“设备不可见”三行确认发现链路（防火墙 53317 入站放行 → AP 隔离关闭 → 接收端系统级网络权限），确认能互见后再用“速度太慢”两行判断是无线频段/加密开销还是平台 I/O 瓶颈；必要时可利用应用内 调试页 与 发现调试页 查看实时发现日志与 HTTP 日志来进一步定位。