LocalSend 全平台使用与构建指南：安装渠道、网络配置到源码级实现剖析

本篇指南基于 LocalSend 项目官方 README（白俄罗斯语版 README_BE.md）整理并深度扩充，系统讲解这款开源跨平台 AirDrop 替代方案的下载渠道与兼容性、防火墙/路由器网络配置、便携模式与隐藏启动参数，以及「无需互联网即可安全传文件」这一核心机制在 Rust 核心库中的实现依据。读完后，你可以独立完成 LocalSend 在各平台的安装、排障、从源码构建（Android/iOS/macOS/Windows/Linux 五个平台命令一应俱全），并理解端口 53317、settings.json 便携模式、--hidden 参数背后的真实代码路径。

LocalSend 是什么

LocalSend 是一款免费、开源的跨平台程序，通过 REST API + HTTPS 加密在局域网内的设备之间安全地交换文件与消息。与依赖外部服务器的其他传输/分享工具不同，LocalSend 不需要互联网连接，也不需要任何第三方服务器——设备之间直接通信，因此是快速、可靠的局域网互联方案。

其核心工作方式：

• 所有数据均通过 HTTPS 传输；
• TLS/SSL 证书在每台设备上即时生成（运行时动态签发），无需依赖任何预置 CA，从源码结构看，该能力由核心库 packages/core/src/crypto/cert.rs 所在的 crypto 模块（含 cert.rs、hash.rs、nonce.rs、token.rs）提供支撑；
• 设备发现与数据传输遵循 LocalSend 自定义协议（官方另有独立的 protocol 文档仓库，本仓库中的协议实现位于 packages/core/）。

下载渠道与平台兼容性

官方建议从应用商店或系统包管理器安装，因为 LocalSend 本身没有自动更新机制。仓库内还收录了各平台的打包配置，例如 app/linux/packaging/deb/make_config.yaml 与 app/linux/packaging/rpm/make_config.yaml。

各平台安装渠道一览

平台	官方渠道
Windows	Microsoft Store、Winget、Scoop、Chocolatey、EXE 安装器、Portable ZIP（后两者从 Releases 最新构建获取）
macOS	App Store、Homebrew、DMG 安装器（Releases 最新构建）
Linux	Flathub、Nixpkgs、Snap、AUR、TAR / DEB / AppImage（Releases 最新构建）
Android	Play Store、F-Droid、APK（Releases 最新构建）
iOS	App Store
Fire OS	Amazon 商店

Windows 二进制文件经过代码签名，签名策略详见 CODE_SIGNING.md。

注意（非官方 MSIX 构建）：基于最新提交的构建可供尝鲜测试，但其稳定性不作保证，全部代码变更会在发布页同步列出。

系统兼容性要求

平台	最低版本	备注
Android	5.0	—
iOS	12.0	—
macOS	11 Big Sur	更旧的 Mac 可借助 OpenCore Legacy Patcher 2.0.2（见上游 issue #1005 的讨论）
Windows	10	支持 Windows 7 的最后一个版本是 v1.15.4，未来可能逆向移植更新版本
Linux	视发行版而定	GNOME 需 xdg-desktop-portal 与 xdg-desktop-portal-gtk；KDE 需 xdg-desktop-portal 与 xdg-desktop-portal-kde

网络配置：防火墙端口与路由器设置

大多数情况下 LocalSend 安装后即可开箱即用。但如果收发文件失败，通常需要放行防火墙并检查路由器设置。

防火墙规则

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

这个 53317 端口不是魔法数字——它就是核心库中广播发现的默认端口，在 packages/core/src/multicast/mod.rs 中定义为常量：

pub const DEFAULT_PORT: u16 = 53317;

仓库内多个测试（packages/core/tests/v2_server.rs、packages/core/tests/v2_tls_pinning.rs）以及 URL 构造逻辑（packages/core/src/http/client/url.rs）都围绕该端口验证了 https://<ip>:53317/api/localsend/v2/... 这类注册/信息接口地址，印证了文档中「入站放行 53317（TCP+UDP）」这条规则的必要性：设备既要通过 UDP 广播被同网段设备发现，也要在该端口上接受对端的 HTTPS 请求。

路由器侧：关闭 AP 隔离（AP Isolation）

请确认路由器上已关闭接入点隔离。它默认在多数路由器上是关闭的，但部分设备（尤其是访客网络场景）会默认开启；一旦开启，客户端之间的连接会被直接禁止，表现为「互相看不到设备」。

桌面端进阶用法

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

在可执行文件所在目录创建一个名为 settings.json 的文件（可以为空文件）。程序会改为把设置保存在该文件里，而不是默认位置。

从源码可以确认其实现：app/lib/util/shared_preferences/shared_preferences_portable.dart 中的 SharedPreferencesPortable 会解析可执行文件路径并在其同级目录拼接 settings.json；当虚拟盘（如 ImDisk 内存盘）导致 Platform.resolvedExecutable 抛异常时，会回退到当前工作目录（见该文件第 30–38 行的容错处理）。判断逻辑位于 app/lib/provider/persistence_provider.dart：在 Windows/Linux/macOS 上检测到该文件存在即启用便携设置并记录日志 Using portable settings.。作为对照，Windows 下默认（非便携）设置路径为 %AppData%\LocalSend\settings.json。

隐藏启动（v1.15.0 更新）

以 --hidden 参数启动可让程序只在系统托盘（通知区域）运行，不显示主窗口：

localsend_app.exe --hidden

在 v1.14.0 及更早版本中，只有当 autostart 参数被传入且「隐藏启动」设置开启时程序才会隐藏启动；v1.15.0 起改为显式的 --hidden 参数。

该参数在源码中是统一常量 app/lib/util/native/autostart_helper.dart 中的 startHiddenFlag = '--hidden'，并且三个平台的开机自启实现都会把它写进启动入口：

• Linux：写入 ~/.config/autostart/<应用名>.desktop 的 Exec= 行；
• Windows：写入注册表 HKCU\Software\Microsoft\Windows\CurrentVersion\Run 的 LocalSend 值；
• macOS：通过 setLaunchAtLoginMinimized 设置为登录时最小化启动。

依赖层次结构

LocalSend 的代码组织遵循清晰的三层依赖，项目内提供了可视化依赖图：

从源码结构看（依据 support/docs/dependency-hierarchy.d2 的定义文件），各层职责为：

层	目录	语言	职责
App	/app/	Dart/Flutter	跨平台图形界面应用（本仓库主工程）
CLI	/cli/	Rust	命令行界面（cli/src/main.rs）
Server	/server/	Rust	WebRTC 信令服务器（server/src/controller/ws_controller.rs）
LocalSend Isolates	/packages/localsend_isolates/	Dart + Rust	后台线程（Isolate）与 Rust 绑定层
Core	/packages/core/	Rust	实现 LocalSend 协议的核心库（发现、HTTP、加密、WebRTC）

App 依赖 Isolates 层，Isolates/CLI/Server 都依赖 Core 层，Core 不反向依赖任何上层。该 SVG 图由 D2 描述文件渲染生成，support/docs/README.md 给出了在仓库根目录重新生成它的命令：

d2 --theme 4 --dark-theme 200 --layout elk --pad 32 support/docs/dependency-hierarchy.d2 support/docs/dependency-hierarchy.svg

从源码运行 LocalSend

按以下步骤可以从源码构建并运行 LocalSend：

1. 安装 Flutter——直接安装或经由 fvm 管理（所需版本见 .fvmrc）；
2. 安装 Rust 工具链；
3. 克隆 LocalSend 仓库；
4. cd app 进入应用目录；
5. flutter pub get 拉取依赖；
6. flutter run 启动应用。

注意（Flutter 版本锁定）：当前仓库通过 .fvmrc 固定 Flutter 版本，其内容为 { "flutter": "3.41.9" }。因此构建问题常常源于「仓库要求的版本」与「本机已安装版本」不一致。为了让开发更可预期，项目推荐使用 fvm 管理 Flutter：安装 fvm 后，用 fvm flutter 替代 flutter 执行命令。

参与贡献

项目欢迎任何形式的外部贡献。

翻译

• 翻译通过 Weblate 平台（localsend/app 项目）协作管理；
• 也可以直接 fork 本仓库手动添加翻译：翻译文件位于 app/assets/i18n/，添加或更新某个语言时编辑对应的 _missing_translations_<locale>.json 或 <locale>.json（例如 app/assets/i18n/zh-CN.json）。生成产物对应 app/lib/gen/ 中的 strings_<locale>.g.dart。

注意：以 @ 开头的字段不需要翻译，程序不会使用它们，它们只是文件或上下文信息，供译者参考。

修 Bug 与功能改进

• 修 Bug：发现问题后直接提交 Pull Request，并清晰描述问题与修复方式；
• 功能改进：先在 issue 区发起讨论，说明改进动机，再动手实现。

完整流程见 CONTRIBUTING.md。

故障排查

问题	平台（发送方）	平台（接收方）	解决方案
设备互相不可见	任意	任意	确认路由器已关闭 AP 隔离；开启时设备间连接会被禁止
设备互相不可见	任意	Windows	确认网络配置文件设为「专用（私人）」；对「公用」网络 Windows 会执行更严格的限制
设备互相不可见	macOS、iOS	任意	尝试在系统设置「隐私」中切换「本地网络」权限的开关
速度过低	任意	任意	改用 5 GHz 频段；并在两台设备上同时关闭加密功能
速度过低	任意	Android	已知问题，源于底层 saf_stream 插件的限制（上游 flutter-cavalry/saf_stream issue #4）

各平台打包构建命令

以下命令面向项目维护者，需在 app/ 目录下执行。

Android

普通 APK：

flutter build apk

Google Play 用的 AppBundle：

flutter build appbundle

iOS

flutter build ipa

macOS

flutter build macos

Windows

普通构建：

flutter build windows

本地 MSIX 包：

flutter pub run msix:create

商店就绪的 MSIX 包：

flutter pub run msix:create --store

Linux

普通构建：

flutter build linux

AppImage：

appimage-builder --recipe AppImageBuilder.yml

Snap：构建说明位于上游独立的 localsend/snap 仓库（本仓库不含该子项目）。

仓库 support/scripts/ 目录中还提供了各平台的自动化打包脚本，可作为上述命令的参考实现，例如 support/scripts/compile_android_apk.sh、support/scripts/compile_windows_msix_signed.ps1、support/scripts/compile_mac_dmg.sh 等。

小结

LocalSend 的价值在于把「局域网传输」做成了零依赖外部服务的方案：设备发现走 UDP 广播（核心库 packages/core/src/multicast/），数据通道走运行时自签证书的 HTTPS（packages/core/src/crypto/），界面层由 Flutter 跨平台承载并通过 Rust 绑定（packages/localsend_isolates/）把重活丢到后台线程。理解上面这份「防火墙 53317 + AP 隔离 + 便携模式 + --hidden」配置清单后，绝大多数「搜不到设备」的问题都能定位到路由器或防火墙层面；而依赖图与 .fvmrc 版本锁定，则为你二次开发或从源码构建提供了明确的可复现前提。