# lanshare **Repository Path**: zkf_dev/lanshare ## Basic Information - **Project Name**: lanshare - **Description**: 同wifi电脑手机文件互传 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-09-18 - **Last Updated**: 2026-10-27 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 隔空互传 · 电脑 ⇄ 手机 文件互传 电脑和手机连同一个 WiFi，就能互相传文件。**手机不用装 App**，扫一下电脑屏幕上的二维码，用浏览器就能传。 原理很简单：电脑上运行一个小程序，起一个只在你家/办公室局域网里的网页服务；手机浏览器连上它，文件就在这两台设备之间直接走，不经过任何云端服务器。 --- ## 一、30 秒上手 1. 电脑连上 WiFi（手机也要连**同一个** WiFi）。 2. 双击文件夹里的 **`隔空互传.exe`**。 - 会打开一个独立应用窗口：没有黑框、没有浏览器地址栏。 - 关闭窗口只是收进托盘，服务继续运行；双击托盘图标可重新打开。 3. 拿起手机，用**相机/浏览器扫码**（二维码就在电脑网页上），直接进入；扫码不方便时，也可以在手机浏览器里输入窗口里显示的地址，再输访问码。 4. 手机上就能： - 点「选择文件 / 照片·视频 / 整个文件夹」上传到电脑； - 在「文件」列表里点任意文件下载到手机，图片/视频/音频/PDF/文本还能直接在线看； - 文件夹或勾选多项后点「打包下载」，会打成一个 zip 传回手机。 电脑 → 手机的反向操作，用的也是这个页面（电脑浏览器里操作即可）。 > 运行环境：Windows 10 / 11 即可，**不需要预装 Node.js**。 > 第一次双击时，启动器会自动下载官方 Node 便携版（约 30 MB，绿色版放在本目录的 `runtime\` 里，不写注册表、不改环境变量、不需要管理员权限），并校验 SHA256；整个过程只有一次。电脑上已经装了 Node 的话会直接复用，不会重复下载。 ### 桌面应用（v1.4+） - 主入口是 **`隔空互传.exe`**：无控制台窗口，界面内嵌在应用窗口中（WebView2），任务栏和托盘都有图标。 - 点窗口右上角关闭 → 隐藏到托盘，共享继续；托盘右键菜单：**打开界面 / 打开共享文件夹 / 在浏览器中打开 / 查看日志 / 重新启动服务 / 退出**。 - 启动失败或服务异常退出时会**弹出错误窗口**并附上最近日志；完整日志在 `logs\lanshare.log`。 - `启动互传.bat` 仍然保留，作为**调试入口**（会显示控制台，方便看实时输出）。 - 依赖系统自带的 WebView2 运行时（Windows 10/11 随 Edge 提供）；如果系统缺失，应用会提示安装。 - 如果程序目录里有 `webview2\MicrosoftEdgeWebview2Setup.exe`（离线完整包已附带），缺少运行时会自动提示并调用该离线安装器。 - 第一次运行且电脑没有 Node 时，会短暂打开一个安装窗口显示下载进度；之后不再出现。 --- ## 二、功能一览 | 功能 | 说明 | | --- | --- | | 手机 → 电脑 | 多选上传、照片/视频批量上传、整个文件夹上传（保留目录结构）、拖拽文件、直接粘贴截图 | | 电脑 → 手机 | 单个下载、文件夹/多选「打包下载」成 zip、图片·视频·音频·PDF·文本在线预览 | | 大文件 | 4 MB 一片分片上传，断网自动重试，续传位置自动校准；实测 128 MB 文件完整传输 | | 同名冲突 | 弹窗选择：覆盖 / 两边都保留（自动改名）/ 跳过，还能「对后面同名的文件都这样处理」 | | 文件管理 | 新建文件夹、重命名、删除（先移到 `.回收站`，可还原） | | 实时同步 | 任何设备上传、删除、重命名，或在电脑资源管理器里直接往共享文件夹放文件，**所有已打开的页面都会自动刷新**，无需手动刷新 | | 剪贴板 | 电脑和手机之间互传文字（网址、验证码、聊天记录），一键复制到本机 | | 连接信息 | 页面上显示二维码、地址、访问码、剩余空间、当前有几台设备在线 | | 隐私 | 6 位访问码保护（扫码自动带上）；文件只在局域网内传输，不经过互联网 | 手机端的核心操作都在一屏里： ``` ┌──────────────────────────────┐ │ 隔空互传 Kefan · 共享文件夹 ●在线 │ ├──────────────────────────────┤ │ 📱 手机连接方式（点开有二维码） │ │ ⬆ 把文件拖到这里 │ │ [选择文件] [照片/视频] [整个文件夹] │ │ 📂 文件列表（下载 / 预览 / 打包 / 删除）│ │ 📋 剪贴板（文字互传） │ └──────────────────────────────┘ ``` --- ## 三、文件放在哪 - 默认共享文件夹：`隔空互传\共享文件夹\`（程序会自动创建）。 - 手机上传的东西直接存到这里，电脑上的资源管理器打开就能看到。 - 删除的东西不会真的消失，会先被移到共享文件夹里的 `.回收站`，在页面底部点「回收站」就能看到并**还原**。 ### 修改共享文件夹位置 **方法一（推荐，电脑上操作）**：打开电脑上的页面，滚动到底部的「设置」→ 点 **更换文件夹** → 在弹出的窗口里选一个目录 → 确认。改完**立即生效**，手机上所有设备的列表会自动切到新目录，并写入 `config.json`，下次启动继续使用。 **方法二（改配置文件）**：在程序目录新建 `config.json`（可复制 `config.example.json` 改名），例如： ```json { "shareDir": "D:\\隔空互传文件", "port": 8765, "name": "我的电脑", "auth": true, "openBrowser": true } ``` `shareDir` 可以写绝对路径，也可以写相对程序目录的路径。保存后重新启动程序生效。 **方法三（临时指定）**：命令行加 `--dir "D:\隔空互传文件"`，只对本次启动生效。 优先级：命令行 `--dir` > `config.json` > 默认目录。注意：切换目录只是换位置，**不会自动搬移旧文件**。 --- ## 四、常见问题 **传完文件另一边要手动刷新吗？** 不用。页面通过 SSE（Server-Sent Events）实时接收变更通知：上传完成、删除、重命名都会立即同步；你在电脑资源管理器里往共享文件夹拖文件，手机上的列表也会自动更新。只有服务被关闭或网络中断时才需要重新打开页面。 **第一次启动时它在下载什么？** 下载的是 Node.js 官方便携版，只把其中的 `node.exe` 放进 `runtime\` 目录，用来运行这个程序本身。它不会安装进系统、不会开机自启、也不修改 PATH。下载源优先用国内的 npmmirror 镜像，失败时自动切到官方源，并用官方 `SHASUMS256.txt` 校验完整性。 **下载失败了怎么办？** 检查网络后重新双击即可。也可以手动下载 `node-v24.22.1-win-x64.zip`（[npmmirror 镜像](https://npmmirror.com/mirrors/node/v24.22.1/)），解压后只把里面的 `node.exe` 放到 `隔空互传\runtime\node.exe`，再双击启动。 **手机扫码后一直转圈 / 打不开？** 多半是 Windows 防火墙拦住了。右键 **`开放防火墙（管理员）.bat`** → 「以管理员身份运行」；或者第一次启动时留意 Windows 弹窗，勾选「专用网络」并点「允许访问」。 **手机和电脑必须怎么连？** 必须连同一个路由器（同一个 WiFi，或电脑插同一个路由器的网线）。手机用 5G 流量、或者连的是另一个网段（比如公司访客网），都连不上。 **电脑上有 VMware / VirtualBox / 无线网卡等多个网卡？** 程序会自动挑真正在用的那张（优先 WiFi 和以太网），启动窗口里带 ★ 的就是手机该用的地址；页面上也会列出可用地址。 **端口 8765 被占用？** 程序会自动往后找一个可用端口，并在启动窗口里显示实际地址和端口。防火墙脚本只开放 8765，如果自动换端口了，需要手动放行对应端口，或用 `--port 8765` 固定。 **手机下载的 zip 怎么打开？** 用系统「文件」应用点一下就解压了。手机下载大文件时建议别锁屏（iOS 锁屏会暂停后台传输，重新点亮屏幕即可继续）。 **关了那个黑窗口会怎样？** 共享就停止了，手机立即连不上。需要时再双击 `启动互传.bat` 即可。文件都留在这台电脑上，不受影响。 **电脑 WiFi 换了（比如从家到公司）？** 地址会变（例如 `http://192.168.18.61:8765` → `http://10.0.0.8:8765`），重新扫一次页面上的二维码就行。 --- ## 五、进阶用法（可选） 命令行参数： | 参数 | 作用 | | --- | --- | | `-d, --dir <目录>` | 指定共享文件夹，例如 `--dir "D:\传文件"` | | `-p, --port <端口>` | 指定端口，默认 8765，被占用时自动往后找 | | `--name <名字>` | 手机上显示的名字，默认电脑主机名 | | `--no-auth` | 关闭访问码（同一网络里任何设备都能访问，公共 WiFi 下别用） | | `--no-open` | 启动后不自动打开浏览器 | | `-h, --help` | 查看帮助 | 配置文件 `config.json` 支持：`shareDir`（共享文件夹）、`port`（端口）、`name`（设备名）、`auth`（是否启用访问码）、`openBrowser`（是否自动打开浏览器）。命令行参数优先级更高。 例子（把共享目录换成 D 盘的「传文件」、端口固定 8765）： ``` node lanshare.js --dir "D:\传文件" --port 8765 ``` 想让开机就自动共享：把 `启动互传.bat` 的快捷方式放进 `shell:startup`（Win+R 输入 `shell:startup` 回车），再把快捷方式的「属性 → 起始位置」留空即可。 --- ## 六、文件说明 ``` 隔空互传/ ├─ 隔空互传.exe ← 双击这个就能用（无控制台桌面应用） ├─ 启动互传.bat ← 调试入口（会显示控制台窗口） ├─ app.ico ← 应用/托盘图标 ├─ Microsoft.Web.WebView2.*.dll / WebView2Loader.dll ← 内嵌浏览器组件 ├─ launcher/ ← 桌面启动器源码（Launcher.cs / build.ps1） ├─ bootstrap.ps1 ← 启动引导：找 Node，没有就自动下载便携版 ├─ config.example.json ← 配置文件示例（复制成 config.json 后修改） ├─ config.json ← 本机配置（自动生成/手动创建，不提交仓库） ├─ 开放防火墙（管理员）.bat ← 手机连不上时，右键以管理员身份运行 ├─ lanshare.js ← 服务端（Node.js，零第三方依赖） ├─ public/ ← 网页界面（HTML/CSS/JS） │ ├─ index.html │ ├─ app.js │ ├─ style.css │ └─ favicon.svg ├─ vendor/qrcode.js ← 二维码生成库（MIT，kazuhikoarase/qrcode-generator） ├─ runtime/node.exe ← 首次运行自动下载的便携版 Node（不进仓库） ├─ logs/lanshare.log ← 桌面应用运行日志（出错时看这里） ├─ 共享文件夹/ ← 默认共享目录（首次运行自动创建） └─ README.md ``` --- ## 七、这批功能是怎么验证过的 交付前做过这些实测（都在本机跑通）： - **接口自动化 46 项全通过**：访问码鉴权、路径穿越拦截（`../`、符号链接越界）、中文/emoji/空格文件名、非法字符清洗、同名冲突三种处理、分片续传与位置校正、Range 断点下载、zip 打包、回收站与还原、剪贴板。 - **实时同步实测**：SSE + 文件系统监听，网页上传、剪贴板更新、重命名、删除、以及用资源管理器直接往共享文件夹拷文件，均能在 0.2~1 秒内推送到所有打开的页面；两个真实浏览器标签页互传时，接收方列表无需刷新即可自动出现新文件。 - **无 Node 环境实测**：清空 PATH 模拟全新电脑，启动器自动从 npmmirror 下载 Node 便携版、通过 SHA256 校验、解压出 `runtime\node.exe`，随后双击 `.bat` 能直接拉起服务（用 Windows PowerShell 5.1 验证）。 - **桌面启动器实测**：启动后无控制台窗口；内嵌页面正常加载（服务端在线列表显示本机 Windows 设备）；关闭窗口后进程与共享服务继续运行；用不存在的目录启动时，1 秒内弹出错误对话框并写入日志。 - **二维码真机解码验证**：把页面上的二维码渲染出来用解码器识别，扫出来的内容与预期网址完全一致（含访问码），确保手机扫码能直接进入。 - **浏览器实测**：用真实浏览器走完上传两个文件、进入文件夹、在线预览文本、批量勾选、打包下载（下载得到的 zip 解压后文件齐全）、删除进回收站、从回收站还原。 - **移动/桌面两种布局**：390px 手机宽度和 1280px 桌面宽度下均无横向溢出，桌面为双栏、手机为单栏且连接卡片默认折叠。 - **大文件性能**：128 MB 文件上传内容校验一致（本机回环 133 MB/s），下载 403 MB/s。真实 WiFi 速度取决于路由器，一般在 20–60 MB/s 之间。