LocalSend 中文使用指南：本地网络传文件的配置、构建与故障排查详解

2026-09-04 18:21:40作者：翟萌耘Ralph

LocalSend 是一个自由开源的跨平台应用，用于在本地网络上与附近设备安全地分享文件和消息，全程无需互联网连接。本篇基于仓库内中文版 README（support/readme/README_ZH.md）整理并扩充，覆盖其核心定位、防火墙与网络配置、便携模式与隐藏式启动等桌面端配置项、从源码构建的完整步骤，以及“设备不可见”“速度太慢”等高频问题的排查方法；读完之后，你可以独立完成 LocalSend 的部署、定制参数与常见故障诊断，并理解其默认端口 53317、多播发现、--hidden 参数背后的实现依据。

关于：无需互联网与第三方服务器的点对点传输

LocalSend 是一个跨平台应用程序，使用 REST API 和 HTTPS 加密实现设备之间的安全通信。与依赖外部服务器的其他消息应用程序不同，LocalSend 不需要互联网连接或第三方服务器，因此成为本地通信的快速可靠解决方案。

这一点在仓库结构中得到印证：项目采用 Flutter（Dart）编写前端与桌面/移动端逻辑，位于 app 目录；核心协议、HTTP 服务与发现机制则用 Rust 实现，位于 packages/core 目录；此外仓库还附带一个命令行工具 cli 和一个独立的 server 组件。

下载与安装

由于应用本身没有自动更新功能，官方建议从应用商店或软件包管理器下载，以便获得持续更新。各平台的安装渠道如下：

Windows	macOS	Linux	Android	iOS	Fire OS
Winget	App Store	Flathub	Play Store	App Store	Amazon
Scoop	Homebrew	Nixpkgs	F-Droid
Chocolatey	DMG 安装包（Releases）	Snap	APK（Releases）
EXE 安装包（Releases）		AUR
绿色版 ZIP（Releases）		TAR（Releases）
		DEB（Releases）
		AppImage（Releases）

各平台最低版本要求（兼容性）

平台	最低版本	备注
Android	5.0	-
iOS	12.0	-
macOS	11 Big Sur	如需在更老的机器上运行，可参考官方 issue 中提到的 OpenCore Legacy Patcher 方案
Windows	10	最后一个支持 Windows 7 的版本是 v1.15.4
Linux	不适用	-

仓库中的 CONTRIBUTING.md 的 Distribution 章节对发行渠道有进一步说明，包维护者（packager）名单也整理在 app/lib/pages/about/packagers.dart 中。

网络与防火墙设置

大多数情况下 LocalSend 应该可以直接使用。如果你在发送或接收文件时遇到问题，可能需要配置防火墙以允许 LocalSend 在本地网络上通信：

流量类型	协议	端口	操作
传入	TCP, UDP	53317	允许
传出	TCP, UDP	任意	允许

为什么是 53317？ 从源码结构看，53317 是 LocalSend 的核心固定端口：CLI 端在 cli/src/storage/config.rs 中定义了 const DEFAULT_PORT: u16 = 53317;，并在首次运行写入的配置模板里以注释形式给出 #port = 53317；Rust 核心库的多播发现测试 packages/core/src/discovery/store.rs 与压力测试示例 packages/core/examples/stress_send.rs 也都默认使用 53317。也就是说，UDP 53317 同时承载“设备发现广播”与“HTTPS 文件传输服务”两个职责，防火墙只需放行这一个入站端口即可。

从 packages/core/src/multicast/socket.rs 的实现可以进一步看到发现机制的细节：设备在每个网络接口上分别绑定一个 UDP 多播 socket（bind_multicast_sockets 函数），显式设置 set_multicast_ttl_v4(1) / set_multicast_hops_v6(1) 把广播限制在本子网内；绑定的是通配地址并开启 loopback，以便同一主机上的多个实例互见，自身消息再由“指纹（fingerprint）”过滤剔除。

路由器设置：请确保禁用路由器上的 AP 隔离（AP Isolation / Client Isolation）。它通常默认关闭，但某些路由器（尤其是访客网络）可能会启用；一旦开启，同一局域网内的设备之间无法直接通信，LocalSend 自然互相发现不了。

桌面端高级配置

便携模式（Portable Mode）

在 v1.13.0 中引入：在与可执行文件相同的目录中创建一个名为 settings.json 的文件（内容可以为空）。应用程序检测到它之后，会把设置写入这个文件而不是默认的持久化位置，从而实现“免安装、随拷随用”。

源码依据在 app/lib/util/shared_preferences/shared_preferences_portable.dart：它返回可执行文件所在目录下 settings.json 的绝对路径，作为 SharedPreferences 的后端；单元测试 app/test/unit/util/shared_preferences/shared_preferences_portable_test.dart 验证了“settings.json 必须与可执行文件同目录”的行为。非便携模式下，Windows 平台的默认设置路径为 %APPDATA%\LocalSend\settings.json，见 app/lib/provider/persistence_provider.dart。

隐藏式启动（Start Hidden）

v1.15.0 起（该节更新于 v1.15.0），使用 --hidden 命令行参数可以只把应用放到系统托盘、不弹出主窗口，例如：

localsend_app.exe --hidden

在 app/lib/config/init.dart 中可以看到，桌面平台启动时会检查启动参数是否包含 startHiddenFlag，命中后调用 hideToTray() 将窗口隐藏；该常量在 app/lib/util/native/autostart_helper.dart 中定义为 const startHiddenFlag = '--hidden';，同一个辅助文件在写入开机自启条目时也会把 --hidden 附加到可执行命令上。

行为沿革（可对照 app/assets/CHANGELOG.md 验证）：

v1.14.0 及更早：若设置了 autostart 标志且应用内开启了“启动时隐藏”设置，应用会自动隐藏式启动；
v1.15.0 起：桌面端统一改为监听 --hidden 参数，自启 + 隐藏的组合更稳定，不再依赖系统设置项联动。

工作原理：设备发现与安全传输

LocalSend 使用安全通信协议，允许设备通过 REST API 进行通信。所有数据都通过 HTTPS 安全地发送，并且 TLS/SSL 证书会在每台设备上动态生成，确保最大的安全性。

对应到源码：

设备发现：基于 UDP 多播（见上文 packages/core/src/multicast/socket.rs），packages/core/src/discovery/store.rs 维护邻居设备的状态；
传输服务：HTTP/HTTPS 服务器实现位于 packages/core/src/http/server，客户端位于 packages/core/src/http/client；
动态证书：TLS 证书生成逻辑在 packages/core/src/crypto/cert.rs，相关行为由测试 packages/core/tests/v2_tls_pinning.rs 等覆盖。

关于 LocalSend 协议（LocalSend Protocol）的完整规范，请查阅项目维护的独立协议文档仓库（README 中链接的外部仓库，本仓库内不再赘述）。

从源码构建

要从源代码编译 LocalSend，请按照以下步骤操作：

安装 Flutter（注意版本要求，见下文说明）；
安装 Rust；
克隆 LocalSend 代码库；
执行 cd app 进入 app 目录；
运行 flutter pub get 下载依赖项；
运行 flutter run 启动应用程序。

注意：Flutter 版本必须匹配。LocalSend 目前使用较新的固定版本 Flutter，仓库根目录的 .fvmrc 明确声明了所需版本：

{
  "flutter": "3.41.9"
}

因此一些构建问题也许是由系统安装的 Flutter 版本与 LocalSend 所需版本不一致导致的。为在开发过程中保持一致性，项目使用 fvm 管理 Flutter 版本：安装 fvm 并 fvm use 拉取对应版本后，开发时应运行 fvm flutter 而不是 flutter。

各平台的一键构建脚本收录在 support/scripts 目录（如 compile_android_apk.sh、compile_mac_dmg.sh、compile_windows_exe.ps1 等），可作为理解打包流程的参考。

贡献

项目欢迎任何希望改进 LocalSend 的贡献者，主要有两种参与方式：

翻译

翻译在 app/assets/i18n 目录。编辑 _missing_translations_<locale>.json 或 strings_<locale>.i18n.json 文件来添加或更新翻译。仓库当前维护了从阿拉伯语到中文简繁在内的数十种语言文件（如 app/assets/i18n/zh-CN.json），每种语言同时有对应的 FlutterGen 生成物 app/lib/gen。

注意： 用 @ 装饰的字段不是用于翻译的；它们在应用程序中没有任何用处，仅仅是关于文件的信息性文本或为翻译者提供上下文。

翻译进度与协作可通过官方 Weblate 平台进行（README 头部的 badge 即指向该平台），也可以 fork 仓库手动提交翻译。

Bug 修复和改进

Bug 修复： 如果发现 bug，请创建一个带有清晰描述问题及解决方法的拉取请求；
改进： 有改进 LocalSend 的想法吗？请先创建一个问题来讨论为什么需要这个改进。

更完整的规范（代码风格、测试要求、发行渠道说明等）见 CONTRIBUTING.md。

故障排查

问题	平台（发送端）	平台（接收端）	解决办法
设备不可见	任何	任何	确保关闭路由器的 AP 隔离。如果 AP 隔离是开着的，设备间的连接会被禁止。
设备不可见	任何	Windows	确保将你的网络配置为“私有”网络。当网络为公共网络时，Windows 会更具限制性。
设备不可见	macOS, iOS	任何	尝试在系统设置的“隐私”下切换“本地网络”权限。
速度太慢	任何	任何	使用 5 GHz 频段；关闭发送和接收端设备的数据加密。
速度太慢	任何	安卓	已知问题，与 Android 文件访问层的实现限制有关，可关注对应上游 issue 的进展。

结合前文的网络配置章节：若上述办法都无效，请再次确认防火墙已放行 TCP/UDP 53317 入站流量，且两端设备处于同一子网（多播发现默认 TTL 为 1，不会跨路由器）。应用内置的调试页面（app/lib/pages/debug 下的发现调试、HTTP 日志与安全调试页）也适合在排查无果时查看底层的发现报文与请求日志。