@hyxf/pairdrop 0.1.2 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/README.md +38 -76
  2. package/bin/pairdrop.js +1 -1
  3. package/dist/assets/{index-BFMfhZgb.js → index-8y9Xz9H5.js} +2 -2
  4. package/dist/assets/index-BgdfyjM6.css +2 -0
  5. package/dist/index.html +2 -2
  6. package/dist-server/server.js +1 -1
  7. package/package.json +15 -27
  8. package/dist/assets/index-Cy2qcAPB.css +0 -2
package/README.md CHANGED
@@ -1,105 +1,67 @@
1
1
  # PairDrop
2
2
 
3
- PairDrop 可在浏览器中帮助附近设备互相发送文件和文本。本仓库包含使用 React 和 TypeScript 编写的客户端，采用 Vite 和 Tailwind CSS 构建；还包含基于 TypeScript、Fastify 和 WebSocket 的服务端，用于设备发现与信令传输。
3
+ PairDrop 让附近设备通过浏览器发送文件和文本。设备连接到同一个 PairDrop 服务后，可以发现彼此；完成配对后即可传输。桌面和移动设备均可使用，目前界面仅提供英文。
4
4
 
5
- ## 功能
5
+ ## 安装与启动
6
6
 
7
- - 发现附近设备；配对后才能发送文件和文本。条件允许时使用 WebRTC，否则可通过 WebSocket 中继传输数据。
8
- - 配对设备以便之后互相发现。
9
- - 设置并保存设备显示名称；通过配对码、邀请链接或系统分享面板（浏览器支持时）分享邀请。
10
- - 保存接收的文件；浏览器支持文件分享时，也可通过系统分享面板分享文件。
11
- - 桌面和移动设备均可使用响应式界面。目前界面仅提供英文。
12
-
13
- 配对邀请支持 `?pair_key=` 链接。本 React 客户端尚未实现旧版 Web Share Target、文件处理器、加密 URL 载荷、按设备配置配对以及主题偏好设置界面。Web App Manifest 未注册分享目标。
14
-
15
- ## 环境要求
16
-
17
- - Node.js 22 或更高版本（与 `package.json` 中的最低版本一致）。
18
- - Yarn Classic 1.22。
19
-
20
- 根据锁文件安装依赖：
7
+ 需要 Node.js 22 或更高版本。通过 npm 安装并启动：
21
8
 
22
9
  ```sh
23
- yarn install
10
+ npm install -g @hyxf/pairdrop
11
+ pairdrop
24
12
  ```
25
13
 
26
- 在同一局域网内使用时，其他设备可以打开运行服务的电脑所提供的局域网地址。请确认操作系统防火墙允许访问服务端口。设备发现和配对需要连接到同一个 PairDrop 信令服务。
27
-
28
- ## 本地开发
14
+ 也可以使用简写命令 `pd`。服务启动后会打印 `http://localhost:3000` 和可用的局域网地址。在其他设备的浏览器中打开打印的局域网地址；这些设备需要能够访问运行 PairDrop 的电脑及其端口，操作系统防火墙也应允许该连接。服务默认监听所有 IPv4 网卡。
29
15
 
30
- 分别在两个终端启动信令服务端和客户端：
16
+ 启动时可选择端口，或自动打开本机浏览器：
31
17
 
32
18
  ```sh
33
- yarn dev:s
19
+ pairdrop --port 4000 --open
34
20
  ```
35
21
 
36
- ```sh
37
- yarn dev:c
38
- ```
22
+ 使用 `pairdrop --help` 查看全部命令行选项。`PORT=4000 pairdrop` 也可设置端口；指定 `--open` 后，可通过 `BROWSER` 环境变量指定浏览器可执行文件。
39
23
 
40
- 服务端默认监听 `3001` 端口，Vite 默认监听 `5173` 端口。请打开 Vite 输出的访问地址。Vite 会将 `/config` 和 WebSocket 路径 `/server` 代理到本地信令服务端。设置 `PORT` 可更改服务端端口；Vite 代理会使用相同端口。
24
+ ## 配对与传输
41
25
 
42
- ## 生产环境
26
+ 1. 在两台设备上打开同一个 PairDrop 服务的地址。附近设备会显示在页面上，但配对前不能发送内容。
27
+ 2. 在一台设备上打开配对窗口，使用另一台设备输入六位配对码，或扫描二维码、打开邀请链接。配对码有效期为五分钟。
28
+ 3. 配对成功后，选择目标设备发送文件或文本。桌面端也可以将文件拖到设备卡片上。
29
+ 4. 接收方确认文件请求后开始传输。传输完成时，请在接收设备上保存文件，或在浏览器支持时通过系统分享面板分享。
43
30
 
44
- ```sh
45
- yarn build
46
- yarn start
47
- ```
31
+ 配对信息和自定义设备名称保存在浏览器本地存储中。清除浏览器数据后需要重新配对；刷新页面前请保存已接收的文件。单次传输最多 100 个文件，总大小不超过 256 MiB。
48
32
 
49
- `yarn build` 生成客户端和服务端 JavaScript；`yarn start` 只运行已构建的命令行工具，不会在每次启动时重新编译。默认监听 `3000` 端口，设置 `PORT` 可更改端口。服务端从 `dist/` 提供构建后的客户端文件。发布 npm 包时，`prepack` 会先生成构建产物。
33
+ 设备优先通过 WebRTC 直连；直连不可用时，本地信令服务默认使用 WebSocket 中继。WebRTC、剪贴板和移动端系统分享等功能受浏览器安全要求限制，建议通过 HTTPS 访问。某些网络环境需要配置 TURN 服务器才能建立 WebRTC 连接。更多行为和限制见[功能清单](docs/FEATURES.md)。
50
34
 
51
- 也可以在构建后通过命令行启动：
35
+ ## 运行配置
52
36
 
53
- ```sh
54
- yarn build
55
- yarn pairdrop
56
- ```
37
+ 启动前可设置以下环境变量：
57
38
 
58
- `pairdrop` CLI 默认只打印访问地址，不会打开浏览器。支持 `--port <端口>` 修改端口、`--open` 启动后打开浏览器，以及 `--help` 查看帮助；使用 `--open` 时可通过 `BROWSER` 指定浏览器可执行文件。CLI 会列出本机局域网 IPv4 地址，生产服务绑定所有 IPv4 网卡，局域网内的其他设备可通过这些地址访问。发布后的 npm 包会提供同名 `pairdrop` 命令；在本仓库使用时可运行 `yarn pairdrop`。CLI 使用构建后的 `dist/` 前端文件和 `dist-server/` 服务端 JavaScript，不会启动 Vite。
39
+ | 变量 | 说明 |
40
+ | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
41
+ | `PORT` | 监听端口，默认为 `3000`；也可使用 `--port`。 |
42
+ | `RTC_CONFIG` | WebRTC `RTCConfiguration` JSON 文件路径，可在其中配置 TURN 服务器；默认使用 Google 公共 STUN 服务器。 |
43
+ | `WS_FALLBACK` | 本地信令服务默认启用 WebSocket 中继；设为 `false` 可关闭。 |
44
+ | `SIGNALING_SERVER` | 使用其他信令服务器，填写不含协议前缀的主机名及可选路径，例如 `pairdrop.example.com`。不能与 `RTC_CONFIG`、`WS_FALLBACK` 或 `IPV6_LOCALIZE` 同时使用。 |
45
+ | `IPV6_LOCALIZE` | 按缩短后的 IPv6 前缀对客户端分组，取值为 `1` 至 `7` 个网段。 |
46
+ | `RATE_LIMIT` | 设为 `true` 启用 HTTP 速率限制，默认为 `false`。 |
47
+ | `TRUSTED_PROXY_IPS` | 受信任反向代理的 IP，多个 IP 用逗号分隔；未设置时不信任转发请求头。 |
48
+ | `LOG_LEVEL` | 服务端日志级别；生产环境默认为 `warn`，可设为 `info` 或 `silent`。 |
49
+ | `DEBUG_MODE` | 设为 `true` 输出诊断日志；日志可能包含配置信息。 |
59
50
 
60
- 本地开发流程保持不变：分别运行 `yarn dev:s` 和 `yarn dev:c`，并访问 Vite 提供的地址。
61
-
62
- `yarn start` 和 `yarn pairdrop` 都会启动生产服务；启动前必须先运行 `yarn build`。若要将服务端口改为 `4000`，可使用 `PORT=4000 yarn start`。运行 `yarn pairdrop --help` 可查看 CLI 参数。
63
-
64
- 单次传输最多 100 个文件、总大小不超过 256 MiB；接收中的文件与尚未关闭的接收文件对话框合计不超过 512 MiB。发送端和接收端按文件计算 CRC32，接收端确认字节数与校验值一致后才回复完成。校验用于发现传输损坏，不用于验证发送者身份。连接服务端或 WebRTC 直连暂时失败时会重试；本地信令服务默认启用 WebSocket 中继，无需设置 `WS_FALLBACK=true`。局域网设备仍须能访问运行 CLI 的电脑及其监听端口；公司网络中的防火墙或网段隔离可能阻止访问。
65
-
66
- 本次传输协议升级后，使用旧页面的设备需要重新打开 PairDrop 页面，再与更新后的服务连接。服务端会拒绝旧协议连接，避免新旧页面对同一文件给出不一致的完成结果。
67
-
68
- 使用 WebRTC 和移动端分享 API 等依赖浏览器能力的功能时，请通过 HTTPS 提供服务。部分网络环境可能需要在 `RTC_CONFIG` 中配置合适的 TURN 服务器才能建立 WebRTC 连接。默认配置仅包含 Google 公共 STUN 服务器。
69
-
70
- ## 配置
71
-
72
- 启动服务端前，可通过环境变量进行配置：
73
-
74
- | 变量 | 说明 |
75
- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
76
- | `PORT` | 监听端口。开发环境默认为 `3001`，生产环境默认为 `3000`。 |
77
- | `RTC_CONFIG` | WebRTC `RTCConfiguration` JSON 文件的路径（包括 `iceServers`）。未设置时，使用 Google STUN 服务器。 |
78
- | `WS_FALLBACK` | 本地信令服务默认启用 WebSocket 中继，WebRTC 直连不可用时用于传输；设置为 `false` 可关闭。 |
79
- | `SIGNALING_SERVER` | 指定要使用的其他信令服务器，填写不含协议前缀的主机名及可选路径，例如 `pairdrop.example.com`。此模式不能与 `RTC_CONFIG`、`WS_FALLBACK` 或 `IPV6_LOCALIZE` 同时使用。 |
80
- | `IPV6_LOCALIZE` | 使用缩短后的 IPv6 前缀对客户端分组，取值为 `1` 至 `7` 个网段。 |
81
- | `RATE_LIMIT` | 设置为 `true` 时启用 HTTP 速率限制，默认为 `false`。仅接受 `true` 或 `false`；代理地址通过 `TRUSTED_PROXY_IPS` 配置。 |
82
- | `LOG_LEVEL` | 设置服务端日志级别。默认为生产环境 `warn`、开发环境 `info`；可设为 `silent` 关闭日志，或设为 `info` 显示请求日志。 |
83
- | `TRUSTED_PROXY_IPS` | HTTP 和 WebSocket 共用的受信任反向代理 IP，多个 IP 用逗号分隔，如 `127.0.0.1`。未设置时不信任转发请求头。代理应覆盖或正确追加 `X-Forwarded-For`，并清理客户端提供的 `CF-Connecting-IP`。 |
84
- | `DEBUG_MODE` | 设置为 `true` 时输出诊断日志。日志可能暴露配置信息，请勿在生产环境中启用。 |
85
-
86
- 例如，使用自定义 RTC 配置并在端口 `4000` 启动：
51
+ 例如，使用自定义 RTC 配置并监听 `4000` 端口：
87
52
 
88
53
  ```sh
89
- PORT=4000 RTC_CONFIG=./rtc-config.json yarn start
54
+ PORT=4000 RTC_CONFIG=./rtc-config.json pairdrop
90
55
  ```
91
56
 
92
- `RTC_CONFIG` 指向 JSON 文件，文件内容应符合浏览器的 WebRTC `RTCConfiguration` 格式。配置中可包含 TURN 服务器；请妥善保护 TURN 凭据。若设置 `SIGNALING_SERVER`，配对信令由指定服务器提供，相关 RTC 和 WebSocket 中继配置应在该信令服务器上设置。
57
+ `RTC_CONFIG` 文件应符合浏览器的 WebRTC `RTCConfiguration` 格式。请妥善保管其中的 TURN 凭据。使用反向代理时，应由代理正确设置 `X-Forwarded-For`，并清理客户端提供的 `CF-Connecting-IP`。
93
58
 
94
- 服务端还会读取 `DONATION_BUTTON_*`、`TWITTER_BUTTON_*`、`MASTODON_BUTTON_*`、`BLUESKY_BUTTON_*`、`CUSTOM_BUTTON_*` 和 `PRIVACYPOLICY_BUTTON_*` 环境变量来配置页脚链接。目前的 React 客户端不会显示这些按钮。
59
+ ## 连接问题排查
95
60
 
96
- ## 检查
61
+ - 看不到其他设备时，确认两台设备打开的是同一个 PairDrop 服务，并检查局域网连通性、防火墙与监听端口。
62
+ - 页面更新后无法连接时，重新打开所有设备上的 PairDrop 页面，避免旧页面继续使用不兼容的传输协议。
63
+ - WebRTC 无法直连时，可保持默认启用的 WebSocket 中继；跨网络使用时，可通过 `RTC_CONFIG` 配置 TURN 服务器，并通过 HTTPS 提供页面。
97
64
 
98
- ```sh
99
- yarn typecheck
100
- yarn lint
101
- yarn format:check
102
- yarn build
103
- ```
65
+ ## 开发
104
66
 
105
- GitHub Actions 会在推送版本标签（名称以 `v` 开头）时运行上述检查，使用 Node.js 22 和 Yarn Classic。`yarn build` 会生成前后端构建产物。目前尚未配置自动化测试。
67
+ 从源码运行、构建、检查和发布项目的方法见[开发文档](docs/DEVELOPMENT.md)。
package/bin/pairdrop.js CHANGED
@@ -113,7 +113,7 @@ function waitUntilReady(child) {
113
113
  async function startPairDrop({ port, open }) {
114
114
  if (!existsSync(distPath) || !existsSync(serverEntry))
115
115
  throw new Error(
116
- 'Built PairDrop files were not found. Run `yarn build` before starting PairDrop.',
116
+ 'Built PairDrop files were not found. Run `pnpm build` before starting PairDrop.',
117
117
  )
118
118
 
119
119
  const child = spawn(process.execPath, [serverEntry], {