Live Share 内网协作失败主因是默认连接微软云服务被拦截,须改用自托管信令服务器并禁用云端服务;需统一 VSCode 版本、校准时钟、配置 DNS/防火墙、透传 WebSocket 头,且通过 /health 接口验证服务可用。

Live Share 无法连接内网服务器的典型表现
你点击“Start Collaboration Session”后,状态栏一直显示 Starting...,几秒后弹出错误:Failed to start collaboration session: Unable to connect to Live Share service。这不是你网络没连上,而是 VSCode 默认尝试连接微软云服务(https://prod.liveshare.vsengsaas.visualstudio.com),而企业防火墙或代理策略直接拦截了该域名或其 CDN 节点。
必须关闭云端中继,改用本地信令服务器
Live Share 默认依赖微软托管的信令/中继服务,这在内网不可行。你需要强制切换为“自托管信令模式”,所有连接协商都走你自己的内网服务器:
- 在 VSCode 中打开命令面板(
Ctrl+Shift+P),运行Live Share: Configure Local Relay Server - 按提示输入内网可访问的地址,例如
http://liveshare.internal:3218(该地址需提前部署好liveshare-server实例) - 编辑工作区
.vscode/settings.json,显式禁用云端服务:{ "liveshare.localRelayServer": "http://liveshare.internal:3218", "liveshare.allowHttpConnections": true, "liveshare.enableCloudServices": false } - 确保所有协作成员都使用同一台信令服务器,并且该服务器能被所有人通过 HTTP 直达(无需反向代理或额外跳转)
内网信令服务器部署与验证要点
微软官方提供开源的 liveshare-server,但企业部署时容易忽略三个关键点:
- 它不自带 HTTPS,若用 HTTPS 反向代理(如 Nginx),必须透传
Upgrade和Connection头,否则 WebSocket 升级失败 - 启动时必须指定
--allowed-origins,例如--allowed-origins="vscode://*" --allowed-origins="http://localhost:*",否则浏览器端拒绝连接 - 信令服务器和 VSCode 客户端的时钟误差不能超过 5 分钟,否则 JWT 鉴权失败 —— 内网机器常因未配置 NTP 同步导致静默失败
- 验证是否就绪:在浏览器中直接访问
http://liveshare.internal:3218/health,返回{"status":"ok"}才算真正可用
协作会话建立后仍卡在“Waiting for guest”
信令通了,但参与者始终看不到对方光标或文件树,常见于以下两种情况:
- VSCode 版本不一致:发起方是 1.85.0,加入方是 1.79.2 —— Live Share 的 P2P 协议版本不兼容,必须统一到同一大版本(如全部 ≥1.84.0)
- 内网 DNS 解析异常:VSCode 尝试用主机名(如
dev01.internal)建立直连,但部分机器 hosts 未映射或 DNS 缓存过期;建议在settings.json中强制指定"liveshare.hostName": "10.1.2.3"(填实际 IP) - Windows 防火墙默认阻止入站 UDP 流量 —— Live Share P2P 使用 UDP 打洞,需手动放行端口范围
3216-3220或临时关闭防火墙测试
内网 Live Share 最难调试的不是连接失败,而是连接成功后数据不通——因为问题分散在信令、P2P、DNS、防火墙、时钟、版本六个层面,任一环节偏差都会导致“看起来连上了,实则无法协作”。建议先用两台同网段虚拟机最小化复现,再逐步放开网络策略。











