LocalSend 局域网文件共享实践：原理剖析、部署配置与跨平台构建指南

本文以 LocalSend 的官方印尼语 README（support/readme/README_ID.md）为主体骨架，覆盖产品定位、工作原理、各平台下载与兼容矩阵、防火墙与路由配置、便携模式与隐藏启动等实战要点，并逐一结合仓库源码佐证其底层实现，帮助读者完整掌握 LocalSend 从部署、网络配置到源码编译、参与贡献的全流程。

LocalSend 是什么

LocalSend 是一款免费开源的跨平台应用，允许用户在局域网内安全地与附近设备共享文件和消息，且无需互联网连接。与普通依赖外部服务器的即时通讯或传输工具不同，LocalSend 使用 REST API 和 HTTPS 加密实现设备间的安全通信，不依赖任何第三方服务器，因此是本地文件传输场景中快速、可靠的方案。

这一“去中心化”设计在仓库中体现得很直接：传输链路完全由设备自身承担，HTTPS 服务端、设备发现（多播）、TLS 身份生成都运行在本机进程中，核心协议实现集中在 packages/core 中，而 Flutter 前端位于 app/lib。

工作原理：REST API + 动态生成的自签名 TLS 证书

README 指出：LocalSend 使用安全的通信协议，设备之间通过 REST API 交互，所有数据经 HTTPS 传输，TLS/SSL 证书在每台设备上动态生成，从而保证安全性。

这一描述可以在源码中得到完整印证：

• 证书动态生成：packages/core/src/crypto/cert.rs 中的 generate_self_signed() 函数在设备上即时生成设备身份——一个 RSA-2048 密钥对加一张自签名证书。源码注释说明了关键设计：
  • 证书主题固定为 CN=LocalSend User，不携带 SAN，因为对端设备仅凭证书指纹（fingerprint）互相识别，名称本身不承载身份信息；
  • 指纹是证书 DER 编码的 SHA-256 值（大写十六进制），即 packages/core/src/crypto/cert.rs 中 fingerprint_from_cert_der() 的输出；
  • 证书有效期取自 rcgen 的默认值（1975 至 4096 年），意味着证书实际上永不因时间过期，无需轮换。
• 默认端口 53317：README 的防火墙表格中出现的 53317 端口，在核心库中定义为常量 DEFAULT_PORT: u16 = 53317，见 packages/core/src/multicast/mod.rs；CLI 端同样以 53317 为缺省值，见 cli/src/storage/config.rs。
• 证书校验：同一文件中还实现了 verify_cert_from_pem / verify_cert_from_der，会依次校验时间有效性、公钥一致性（若提供了期望公钥）以及证书签名，这正是“配对设备”防仿冒能力的底层依据。

可以推断，正因为证书是本地自签且指纹作为设备身份，LocalSend 才能在不联网、无 CA 的情况下完成端到端加密与设备识别。

下载与平台兼容性

README 建议优先通过应用商店或包管理器安装，因为应用本身没有自动更新功能。各平台可用的分发渠道如下：

平台	分发渠道
Windows	Microsoft Store、Winget、Scoop、Chocolatey、EXE 安装器、便携版 ZIP（后两者可从官方最新 release 获取）
macOS	App Store、Homebrew、DMG 安装器
Linux	Flathub、Nixpkgs、Snap、AUR，以及 TAR / DEB / AppImage 原始包
Android	Google Play、F-Droid、APK
iOS	App Store
Fire OS	Amazon 商店

关于分发渠道的详细说明，可参考仓库中的 CONTRIBUTING.md 与 CODE_SIGNING.md（Windows 二进制均经过代码签名）。

兼容性矩阵（原文档完整保留）：

平台	最低版本	说明
Android	5.0	-
iOS	12.0	-
macOS	11 Big Sur	旧机型需配合 OpenCore Legacy Patcher 2.0.2 使用
Windows	10	最后一个支持 Windows 7 的版本是 v1.15.4，未来可能有回移植
Linux	N.A.	依赖：GNOME 需 xdg-desktop-portal 与 xdg-desktop-portal-gtk；KDE 需 xdg-desktop-portal 与 xdg-desktop-portal-kde

说明：以上兼容数据来自 README 的表述。按当前仓库 app/pubspec.yaml 的版本号，主线版本已推进到 1.18.2，因此“最后支持 Windows 7 的版本为 v1.15.4”这一结论只适用于该历史版本。

网络与防火墙配置

绝大多数情况下 LocalSend 开箱即用；若发送或接收文件出现问题，需配置防火墙放行本地网络通信。原文档给出的放行规则如下，可直接照抄到 Windows 防火墙、iptables 或路由器策略中：

流量方向	协议	端口	动作
入站 (Incoming)	TCP、UDP	53317	允许 (Allow)
出站 (Outgoing)	TCP、UDP	任意	允许 (Allow)

其中 53317 既是 HTTP(S) 服务端口，也是设备发现使用的多播默认端口（前文 packages/core/src/multicast/mod.rs 中的 DEFAULT_PORT），因此 TCP 和 UDP 都需放行。

此外还要关闭路由器上的 AP 隔离（AP-Isolation）。该功能通常默认关闭，但部分路由器（尤其是访客网络）会将其开启；一旦开启，AP 下各设备之间无法直接通信，LocalSend 的设备互发现将完全失效。

进阶用法：便携模式与隐藏启动

便携模式（Portable Mode）

（v1.13.0 引入）

在与可执行文件同一目录下创建一个名为 settings.json 的文件（内容可以为空），应用即会改用该文件保存设置，而不是默认的持久化位置。这使整个应用可以放在 U 盘等可移动介质上携带使用。

该功能的实现位于 app/lib/util/shared_preferences/shared_preferences_portable.dart：SharedPreferencesPortable 是一个自定义的 SharedPreferences 存储后端，通过 buildSettingsPath() 将配置路径解析为“可执行文件父目录 + settings.json”；源码还处理了一个边缘场景——某些虚拟磁盘（如 ImDisk 内存盘）上读取 Platform.resolvedExecutable 会抛异常导致应用崩溃，此时会回退到当前工作目录。

隐藏启动（Start Hidden）

（v1.15.0 更新）

若希望应用启动后不出现在任务栏、仅驻留系统托盘，使用 --hidden 命令行参数，例如：

localsend_app.exe --hidden

从源码看，该参数在 app/lib/util/native/autostart_helper.dart 中定义为 startHiddenFlag = '--hidden'，并在启动流程 app/lib/config/init.dart 中被解析：若桌面平台命令行包含该 flag，则调用 hideToTray() 将窗口隐藏到托盘；否则显示主窗口。

版本行为差异：v1.14.0 及更早版本中，应用是在 autostart（开机自启）开启且“隐藏”设置被勾选时才会隐藏启动；v1.15.0 起改为显式的 --hidden 参数，语义更明确。

从源码编译运行（Memulai）

若要使用源码编译 LocalSend，按原文档步骤操作：

1. 安装 Flutter（直接安装，或使用 fvm 管理版本，所需版本见 .fvmrc）
2. 克隆 LocalSend 仓库
3. 运行 cd app 进入应用目录
4. 运行 flutter pub get 下载依赖
5. 运行 flutter run 启动应用

原文档特别提示：LocalSend 当前需要较旧（特定）的 Flutter 版本，若系统安装的 Flutter 版本与要求不符，可能出现构建问题。当前仓库的 .fvmrc 锁定的版本为 Flutter 3.41.9。为保持开发环境一致，项目推荐使用 fvm 管理 Flutter 版本——安装 fvm 后，用 fvm flutter 替代 flutter 命令即可。

另外，桌面端包含 Rust 原生核心（见 packages/localsend_isolates/rust），完整桌面构建还需要 Rust 工具链，版本要求见仓库根的 rust-toolchain.toml。

参与贡献（Berkontribusi）

LocalSend 欢迎任何形式的新手贡献，主要有两条路径：

翻译

推荐方式为通过 Weblate 平台管理翻译；替代方式是 fork 仓库手动添加。翻译文件位于 app/assets/i18n 目录，编辑 _missing_translations_<locale>.json 或 strings_<locale>.i18n.json 即可新增或更新译文——当前该目录已包含印尼语（id.json）、中文（zh-CN.json）等 60 余种语言文件。

注意（原文档特别强调）：以 @ 开头的字段不是用于翻译的内容，它们不在应用中使用，只是为译者提供上下文的说明性文字。

缺陷修复与功能改进

• Bug 修复：发现 bug 后直接创建 PR，需清晰描述问题及修复方式；
• 功能改进：先创建 issue 讨论改进的必要性，再动手实现。

更多规范请参阅 CONTRIBUTING.md。

故障排查（Pemecahan Masalah）

原文档给出的排查表完整保留如下，覆盖了“设备互不可见”与“传输过慢”两类最常见问题：

问题	发送端平台	接收端平台	解决方案
设备不可见	任意	任意	确认已关闭路由器的 AP-Isolation。若开启，设备间连接会被禁止
设备不可见	任意	Windows	将网络类型配置为“专用（private）”网络。Windows 在“公用（public）”网络下限制更严格
设备不可见	macOS、iOS	任意	尝试在系统“隐私”设置中反复切换“本地网络（Local Network）”权限
速度太慢	任意	任意	改用 5 GHz 频段；在两台设备上均关闭加密
速度太慢	任意	Android	已知问题（源自 Android SAF 流式读取限制，参见 flutter-cavalry/saf_stream 项目 issue #4）

排查顺序建议：先确认路由 AP 隔离与同网段（设备发现依赖多播，跨网段/隔离 VAP 必然失败），再按接收端平台核对系统级网络与隐私权限，最后针对慢速问题切换 5 GHz 频段或关闭加密验证是否为带宽/加密开销问题。

小结

LocalSend 的核心价值在于“纯局域网 + 本地自签 TLS + 设备指纹识别”的组合：无需互联网、无需第三方服务器，每台设备用本地生成的 RSA-2048 自签名证书（见 packages/core/src/crypto/cert.rs）完成加密与身份认证。对使用者而言，记住三件事即可：防火墙放行 53317 端口的 TCP/UDP、关闭路由 AP 隔离、Windows 下将网络设为专用网络；对桌面用户可额外利用 settings.json 便携模式和 --hidden 托盘启动；对开发者则可用 fvm 锁定 Flutter 3.41.9 后按 flutter pub get + flutter run 流程快速跑起源码。