LocalSend 局域网文件分享指南：网络配置、隐藏启动与源码构建实践

LocalSend 是一款免费、开源的跨平台应用，让你无需互联网连接，就能通过局域网在附近设备之间安全地交换文件和消息。本篇基于仓库的俄语版官方说明（support/readme/README_RU.md）展开，覆盖安装渠道、防火墙端口放行、便携模式与后台启动参数、底层 TLS 通信机制，以及如何用 Flutter + Rust 双技术栈从源码编译运行，并附完整的故障排查对照表。

LocalSend 是什么

LocalSend 是一个跨平台应用，通过 REST API 与 HTTPS 加密实现设备之间的安全通信。与依赖外部服务器的其他传文件应用不同，LocalSend 不需要互联网或任何第三方服务器，因此它是本地通信场景下快速、可靠的方案：

• 纯局域网工作：设备发现与文件传输都发生在局域网内，断网也能用；
• 端到端加密：所有数据通过 HTTPS 传输，TLS 证书在每台设备上即时生成；
• 多平台覆盖：Windows、macOS、Linux、Android、iOS、Fire OS。

下载与分发渠道

官方建议从应用商店或系统包管理器安装，因为应用本身没有自动更新机制。各平台可用的分发渠道如下（具体下载入口以官方渠道为准）：

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（最新 Release）
EXE 安装包		AUR
便携 ZIP		TAR / DEB / AppImage（最新 Release）

平台兼容矩阵

平台	最低版本	备注
Android	5.0	-
iOS	12.0	-
macOS	11 Big Sur	旧版本 macOS 可借助 OpenCore Legacy Patcher 2.0.2 安装
Windows	10	最后一个支持 Windows 7 的版本是 v1.15.4，后续是否会回移支持未定
Linux	无硬性要求	依赖发行版包管理

从仓库配置看，当前主干版本的 Android targetSdkVersion 为 37（app/android/app/build.gradle），iOS 部署目标在 app/ios/Runner.xcodeproj/project.pbxproj 中按构建设置为 13.0/16.0，应用版本号见 app/pubspec.yaml。

网络配置：防火墙与路由要求

大多数情况下 LocalSend 开箱即用，但如果收发文件出现问题，通常需要配置防火墙允许 LocalSend 与局域网通信：

流量方向	协议	端口	操作
入站	TCP、UDP	53317	允许
出站	TCP、UDP	任意	允许

53317 是 LocalSend 的默认服务端口。这一点在仓库中可以得到多处印证：CLI 端默认端口常量定义在 cli/src/storage/config.rs（const DEFAULT_PORT: u16 = 53317），CLI 启动参数也说明 --port 缺省即 53317（见 cli/src/main.rs）；核心包的 URL 构造与设备发现测试同样以 53317 为基准（packages/core/src/http/client/url.rs、packages/core/src/discovery/store.rs）。

除了防火墙，还需确保路由器的接入点隔离（AP Isolation）已关闭。它通常默认关闭，但在部分路由器（尤其是访客网络）上会被开启。开启后设备之间的连接会被直接阻断，导致互相无法发现。

便携模式：settings.json

自 v1.13.0 起，LocalSend 支持便携模式：在可执行文件所在目录创建一个名为 settings.json 的文件（可以为空），应用会改用该文件存储设置，而不是默认的本地数据位置。

这一行为的实现在 app/lib/util/shared_preferences/shared_preferences_portable.dart：SharedPreferencesPortable 通过 _resolveExecutable() 解析当前可执行文件路径，再用 buildSettingsPath() 拼出同目录下的 settings.json。值得注意的是，代码对解析可执行路径做了容错——在 ImDisk 内存盘等虚拟磁盘上 Platform.resolvedExecutable 可能抛 TypeError，此时会回退到当前工作目录，避免应用启动前崩溃。对应测试位于 app/test/unit/util/shared_preferences/shared_preferences_portable_test.dart。而在未启用便携模式时，Windows 上的默认路径是 %APPDATA%\LocalSend\settings.json（见 app/lib/provider/persistence_provider.dart）。

便携模式的实用价值：把 localsend_app.exe（或 Linux 可执行文件）连同 settings.json 一起放进 U 盘或移动目录，设置随目录走，卸载/迁移不丢失。

隐藏（后台）启动

自 v1.15.0 起，使用 --hidden 标志可以让应用仅驻留托盘而不显示主窗口：

localsend_app.exe --hidden

版本差异需要注意：v1.14.0 及更早版本中，只有同时满足 --autostart 标志和“隐藏启动”设置两项条件时才会隐藏启动。参数解析与启动流程位于应用配置初始化逻辑 app/lib/config/init.dart 及 app/lib/main.dart 中。

工作原理：REST API + 即时生成的 TLS

LocalSend 使用一套安全的通信协议，设备之间通过 REST API 交互。所有数据经 HTTPS 传输，TLS/SSL 证书在每台设备上即时生成，不依赖任何证书颁发机构或外部服务。

仓库核心包 packages/core 的实现可以印证这一机制：

• packages/core/src/crypto/cert.rs 中 generate_self_signed() 生成设备身份：RSA-2048 密钥对 + 自签名证书，CN=LocalSend User，有效期极长（1975～4096 年），实际永不因时间过期；
• 设备的唯一标识是证书 DER 编码的 SHA-256 指纹（大写十六进制），对端之间纯粹靠指纹互相识别，证书名称不携带任何信息；
• packages/core/src/crypto/mod.rs、packages/core/src/crypto/nonce.rs 与 packages/core/src/crypto/token.rs 分别提供哈希、一次性 nonce 与请求令牌，防止重放；
• 设备发现基于组播（packages/core/src/multicast），HTTP 服务端与客户端分别在 packages/core/src/http/server 与 packages/core/src/http/client；此外还提供 WebRTC 通道（packages/core/src/webrtc）以支持更复杂的网络拓扑。

协议细节以独立的 protocol 项目文档为准，仓库内可用测试 packages/core/tests（如 v2_tls_pinning.rs、discovery.rs）验证了 TLS 固定与发现的真实行为。

从源码构建

从源码编译 LocalSend 需要 Flutter 与 Rust 两个工具链：

1. 安装 Flutter（官方渠道或使用 fvm 管理，所需版本见 .fvmrc，当前为 Flutter 3.41.9）；
2. 安装 Rust（工具链版本固定见 rust-toolchain.toml，当前为 1.97.1 并启用 clippy）；
3. 克隆 LocalSend 仓库；
4. 进入应用目录：cd app；
5. 拉取依赖：flutter pub get；
6. 运行应用：flutter run。

注意：LocalSend 要求 .fvmrc 中指定的特定 Flutter 版本，系统安装的 Flutter 版本与之不匹配时可能出现构建问题。为保持开发环境一致，LocalSend 使用 fvm 管理项目 Flutter 版本：安装 fvm 后，请用 fvm flutter 代替 flutter 执行命令。

架构上，Flutter 前端（app）通过 flutter_rust_bridge 调用 Rust 核心：桥接层位于 packages/localsend_isolates，其中 rust/ 目录是原生实现、lib/rust/ 是生成的 Dart FFI 绑定（frb_generated.dart 等），核心网络逻辑则复用 packages/core。另有独立 CLI（cli）提供命令行收发能力，以及可选的 WebSocket 网关服务（server）。各平台发布构建脚本集中在 support/scripts（如 compile_linux_appimage.sh、compile_windows_exe.ps1、compile_android_apk.sh），CI 工作流见 .github/workflows/ci.yml 及各平台的 build_*.yml。

参与贡献

翻译

推荐方式是通过 Weblate 平台管理翻译；也可以通过 fork 仓库手动添加翻译。翻译文件位于 app/assets/i18n 目录，编辑 _missing_translations_<locale>.json 或对应的 strings_<locale> 文件即可添加或更新译文。当前仓库内已包含 70 余种语言的翻译文件（ar、de、fr、ja、ko、pt-BR、ru、zh-CN、zh-TW 等）。

注意：字段值中包含 @ 符号的条目不是待翻译文本，它们仅是向译者说明文件上下文或提供信息用的注释性文字，应用中并不使用，请勿翻译。

缺陷修复与改进

• 修 Bug：发现缺陷后，提交带有清晰问题描述与解决方式的 Pull Request；
• 改进建议：对 LocalSend 有改进想法时，先开 Issue 讨论为何需要该改进。

更多流程细节见 CONTRIBUTING.md（含分发渠道说明）。

故障排查对照表

问题	平台（发送方）	平台（接收方）	解决方案
设备不显示	任意	任意	确认路由器已关闭接入点隔离；开启会阻断设备间连接
设备不显示	任意	Windows	确认网络类型设置为“专用”；Windows 对公用网络施加额外限制
设备不显示	macOS、iOS	任意	在系统“隐私”设置中重新授予“本地网络”权限
速度过慢	任意	任意	改用 5 GHz Wi-Fi；两台设备都关闭加密
速度过慢	任意	Android	已知问题（saf_stream 插件相关），可在上游跟踪

延伸阅读

• 英文主文档：README.md（其他语言版本见 support/readme 目录）
• 更新日志：app/assets/CHANGELOG.md
• 核心 Rust 包：packages/core/src（crypto / discovery / http / multicast / webrtc）
• 前端入口：app/lib/main.dart、app/lib/config/init.dart