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

LocalSend 中文使用指南本地网络传文件的配置、构建与故障排查详解【免费下载链接】localsendAn open-source cross-platform alternative to AirDrop项目地址: https://gitcode.com/GitHub_Trending/lo/localsendLocalSend 是一个自由开源的跨平台应用用于在本地网络上与附近设备安全地分享文件和消息全程无需互联网连接。本篇基于仓库内中文版 READMEsupport/readme/README_ZH.md整理并扩充覆盖其核心定位、防火墙与网络配置、便携模式与隐藏式启动等桌面端配置项、从源码构建的完整步骤以及“设备不可见”“速度太慢”等高频问题的排查方法读完之后你可以独立完成 LocalSend 的部署、定制参数与常见故障诊断并理解其默认端口 53317、多播发现、--hidden参数背后的实现依据。关于无需互联网与第三方服务器的点对点传输LocalSend 是一个跨平台应用程序使用 REST API 和 HTTPS 加密实现设备之间的安全通信。与依赖外部服务器的其他消息应用程序不同LocalSend 不需要互联网连接或第三方服务器因此成为本地通信的快速可靠解决方案。这一点在仓库结构中得到印证项目采用 FlutterDart编写前端与桌面/移动端逻辑位于 app 目录核心协议、HTTP 服务与发现机制则用 Rust 实现位于 packages/core 目录此外仓库还附带一个命令行工具 cli 和一个独立的 server 组件。下载与安装由于应用本身没有自动更新功能官方建议从应用商店或软件包管理器下载以便获得持续更新。各平台的安装渠道如下WindowsmacOSLinuxAndroidiOSFire OSWingetApp StoreFlathubPlay StoreApp StoreAmazonScoopHomebrewNixpkgsF-DroidChocolateyDMG 安装包ReleasesSnapAPKReleasesEXE 安装包ReleasesAUR绿色版 ZIPReleasesTARReleasesDEBReleasesAppImageReleases各平台最低版本要求兼容性平台最低版本备注Android5.0-iOS12.0-macOS11 Big Sur如需在更老的机器上运行可参考官方 issue 中提到的 OpenCore Legacy Patcher 方案Windows10最后一个支持 Windows 7 的版本是 v1.15.4Linux不适用-仓库中的 CONTRIBUTING.md 的 Distribution 章节对发行渠道有进一步说明包维护者packager名单也整理在 app/lib/pages/about/packagers.dart 中。网络与防火墙设置大多数情况下 LocalSend 应该可以直接使用。如果你在发送或接收文件时遇到问题可能需要配置防火墙以允许 LocalSend 在本地网络上通信流量类型协议端口操作传入TCP, UDP53317允许传出TCP, UDP任意允许为什么是 53317从源码结构看53317是 LocalSend 的核心固定端口CLI 端在 cli/src/storage/config.rs 中定义了const DEFAULT_PORT: u16 53317;并在首次运行写入的配置模板里以注释形式给出#port 53317Rust 核心库的多播发现测试 packages/core/src/discovery/store.rs 与压力测试示例 packages/core/examples/stress_send.rs 也都默认使用 53317。也就是说UDP 53317 同时承载“设备发现广播”与“HTTPS 文件传输服务”两个职责防火墙只需放行这一个入站端口即可。从 packages/core/src/multicast/socket.rs 的实现可以进一步看到发现机制的细节设备在每个网络接口上分别绑定一个 UDP 多播 socketbind_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 Hiddenv1.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.rspackages/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 日志与安全调试页也适合在排查无果时查看底层的发现报文与请求日志。参考中文版 README 原文support/readme/README_ZH.md注意中文文档更新可能不够及时请以英文文档 README.md 为准英文及其他 17 种语言版本位于 support/readme 目录更新历史CHANGELOG.md 与 app/assets/CHANGELOG.md核心协议实现packages/core/src命令行工具cli/src【免费下载链接】localsendAn open-source cross-platform alternative to AirDrop项目地址: https://gitcode.com/GitHub_Trending/lo/localsend创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考