remote-dev-sync

远程沙箱同步本地包源码的开发工具，支持 Vite / Rspack / Webpack，带热更新。

适用场景

你在本地开发 npm 包（如 monorepo 中的若干子包），远程沙箱中的项目依赖这些包。你希望本地改代码后，远程沙箱能自动拉取最新的构建产物并热更新，不需要重新发包。

安装

# 全局安装（推荐，可直接使用 remote-dev-sync 命令）
npm install -g remote-dev-sync

# 或项目内安装
npm install remote-dev-sync --save-dev

快速开始

第一步：本机一键启动

在你的 monorepo 根目录下：

# 生成配置文件模板
remote-dev-sync init

编辑 .remote-dev.config.json：

{
  "packages": ["@your-scope/package-a", "@your-scope/package-b"],
  "buildCommand": "yarn turbo dev {filters}",
  "tunnel": true
}

buildCommand 是本地构建 watch 的启动脚本，常见写法：

// turbo monorepo（yarn / pnpm）
{ "buildCommand": "yarn turbo dev {filters}" }
{ "buildCommand": "pnpm turbo dev {filters}" }

// lerna monorepo
{ "buildCommand": "lerna run dev --scope={packages}" }

// 单包项目，直接写死命令
{ "buildCommand": "npm run dev" }
{ "buildCommand": "tsup --watch" }

• {filters} 会展开为 --filter=@scope/pkg-a --filter=@scope/pkg-b
• {packages} 会展开为 "@scope/pkg-a" "@scope/pkg-b"
• 不配置时自动检测：有 turbo.json 则用 turbo dev，否则跳过（你可以自己在另一个终端跑构建）

monorepo 不传则默认为配置文件所在目录。如果 monorepo 在别处，传绝对路径："monorepo": "/path/to/monorepo"。

# 一键启动：构建 watch + 文件服务 + 隧道
remote-dev-sync start

启动后会输出远程沙箱需要的配置：

========================================
  READY!
========================================
  Tunnel URL: https://xxx-xxx-xxx.loca.lt
  Local URL:  http://localhost:8787

  Remote .remote-dev.json:
{
    "remote": "https://xxx-xxx-xxx.loca.lt",
    "packages": ["@your-scope/package-a"],
    "mode": "ws"
}
========================================

第二步：远程沙箱配置

在远程项目中安装：

npm install remote-dev-sync --save-dev

在远程项目根目录创建 .remote-dev.json（直接复制上面输出的内容）：

{
  "remote": "https://xxx-xxx-xxx.loca.lt",
  "packages": ["@your-scope/package-a"],
  "mode": "ws"
}

建议将 .remote-dev.json 加入 .gitignore，每个人的隧道 URL 不同。

在构建配置中加入插件：

Vite（vite.config.ts）：

import { viteRemoteDev } from 'remote-dev-sync';

export default defineConfig({
  plugins: [
    viteRemoteDev(),  // 自动读取 .remote-dev.json
  ]
});

Rspack / Webpack（rspack.config.js）：

const { RemoteDevPlugin } = require('remote-dev-sync');

module.exports = {
  plugins: [
    new RemoteDevPlugin(),  // 自动读取 .remote-dev.json
  ]
};

第三步：启动远程 dev server

npm run dev

之后你在本机改代码：

• ws 模式：~300ms 内自动同步并热更新
• http 模式：~10s 内（取决于 poll 间隔）自动同步并热更新

配置参考

.remote-dev.config.json（本机）

| 字段 | 类型 | 必填 | 默认值 | 说明 | |------|------|------|--------|------| | packages | string[] | 是 | — | 要同步的包名列表 | | monorepo | string | 否 | 配置文件所在目录 | Monorepo 根目录路径 | | port | number | 否 | 8787 | 本地文件服务端口 | | tunnel | boolean | 否 | true | 是否启动 localtunnel 内网穿透 | | buildCommand | string | 否 | 自动检测 | 构建 watch 命令，支持 {filters} 和 {packages} 模板变量 |

buildCommand 说明：不配置时自动检测（有 turbo.json 则用 turbo dev）。自定义示例：

{ "buildCommand": "pnpm turbo dev {filters}" }
{ "buildCommand": "lerna run dev --scope={packages}" }
{ "buildCommand": "npm run build:watch" }

• {filters} → --filter=@my/ui --filter=@my/utils
• {packages} → "@my/ui" "@my/utils"

.remote-dev.json（远程沙箱）

| 字段 | 类型 | 必填 | 默认值 | 说明 | |------|------|------|--------|------| | remote | string | 是 | — | 本机文件服务地址（隧道 URL 或内网 IP） | | packages | string[] | 是 | — | 需要同步的 npm 包名列表 | | mode | "ws" | "http" | 否 | "http" | 同步模式：ws=WebSocket 推送（推荐），http=轮询 | | poll | number | 否 | 3000 | http 模式的轮询间隔（毫秒），ws 模式下忽略 |

也可以通过代码传参（优先级高于 .remote-dev.json）：

// ws 模式（推荐）
viteRemoteDev({
  remote: 'http://192.168.1.100:8787',
  packages: ['@my/ui'],
  mode: 'ws',
})

// http 模式
viteRemoteDev({
  remote: 'http://192.168.1.100:8787',
  packages: ['@my/ui'],
  mode: 'http',
  poll: 5000,
})

CLI 命令

remote-dev-sync start — 一键启动（推荐）

remote-dev-sync start                    # 使用当前目录的 .remote-dev.config.json
remote-dev-sync start ./my-config.json   # 指定配置文件

remote-dev-sync serve — 手动参数启动

# 暴露 monorepo 中的所有包
remote-dev-sync serve --monorepo /path/to/monorepo --tunnel

# 只暴露特定包
remote-dev-sync serve --monorepo /path/to/monorepo --filter ui --filter utils

# 单包模式
remote-dev-sync serve --pkg @my/ui=/path/to/ui

# 同时执行构建命令
remote-dev-sync serve --monorepo /path/to/monorepo --exec "yarn turbo dev --filter=@my/pkg" --tunnel

| 参数 | 说明 | |------|------| | --port <port> | 服务端口（默认 8787） | | --host <host> | 绑定地址（默认 0.0.0.0） | | --monorepo <path> | Monorepo 根目录，自动扫描子包 | | --filter <keyword> | 按关键字过滤包名（可重复） | | --pkg <name>=<path> | 手动指定包名=路径（可重复） | | --exec <command> | 同时执行的命令（如构建 watch） | | --tunnel | 启动 localtunnel 内网穿透 |

remote-dev-sync init — 生成配置模板

remote-dev-sync init

项目内安装时，以上命令用 npx remote-dev-sync 代替。

常见问题

隧道 URL 每次启动都变？

是的，localtunnel 免费版每次分配随机域名。启动后需要更新远程沙箱的 .remote-dev.json。

同步很慢？

• 默认只同步 lib/、dist/、package.json（构建产物），不会同步 src/、tests/ 等源码
• 使用 /bundle 接口一次请求拉取所有文件，避免多次请求被限流
• 可以通过减少 packages 中的包数量来加速

macOS 防火墙拦截？

如果使用内网直连模式，需要给 Node.js 加防火墙白名单：

sudo /usr/libexec/ApplicationFirewall/socketfilterfw --add $(which node)
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --unblockapp $(which node)

远程报错 HTTP 429？

推荐切换到 mode: "ws"，WebSocket 长连接不会触发限流。如果使用 http 模式，确保 poll 设为 10000（10 秒）或更大。

远程报错 HTTP 408？

请求超时。插件内置 120 秒超时，如果包文件过多可以：

1. 减少同步的包数量
2. 检查网络连通性：curl -H "Bypass-Tunnel-Reminder: true" <tunnel-url>/packages

更多文档

• 服务接口（HTTP + WebSocket）
• 架构与实现细节