问题排查

English · 简体中文 · 文档中心

按遇到的现象查找下方说明，恢复正常后就不必继续。 如果问题仍然存在，可以收集诊断报告反馈。

常见问题

你遇到的情况	可以先试什么
App 启动失败，或没有自动打开网页	查看页面和终端中的原因；App 仍在运行时可复制终端中的地址打开。按 App 运行与诊断说明收集报告；本地模式提示多个地址时，在启动页选择网卡和 IP。
公网邀请创建失败，或打开链接出现 1033	按公网邀请排查检查房主 App 和当前链接。
本地邀请打不开	确认两台设备在同一网络且可以互相访问。访客 Wi-Fi 或防火墙规则可能阻止本地连接。
输入房间号后提示房间不存在	先打开房主最新的完整邀请链接。房间号只在原站点有效；站点开启空房间回收时，旧房间也可能已被回收，由房主重新创建即可。参阅加入房间。
无法创建房间 (403)	自建站点请联系管理员检查允许访问的站点地址。
站点房间号已用满	稍后重试或使用其他 VeScreen 站点；管理员可配置空房间回收。这与单个房间的观众人数上限不同。
没有屏幕选择弹窗	按系统提示允许浏览器或 App 录制屏幕。浏览器采集需要 HTTPS 或 localhost，请在电脑上尝试分享。
App 的窗口或屏幕列表为空	先查看选源器中的提示，再按 App 来源排查 操作；也可以选 浏览器 → 选择画面，在浏览器弹窗中选择屏幕、窗口或标签页。
选源后提示分享失败	点击电视下方的错误图标查看原因和排查入口，按分享启动排查逐步对照。
H264 无法开播，或选源后立即退回未分享状态	先试 自动 或 VP8，再按 Windows H264 与显卡排查操作。
游戏黑屏、只显示桌面，或进入游戏后停止分享	对照其他来源和窗口模式，按游戏采集排查操作。
HDR 画面过亮或颜色发白	Windows 上可改用 App 选源，或暂时关闭 HDR；查看 HDR 说明。
分享的窗口或屏幕周围出现黄框	这是 Windows 的采集提示。查看采集边框说明，了解 Windows 11 的开关和 Windows 10 的可选处理方法。
有画面，没来源声音	先取消视频静音。房主应选择支持分享声音的来源，并在选源器中打开声音。摄像头画面与音频输入分别选择，见声音设置。
听不到房主说话	房主可在画面下方开启 麦克风，在 设置 → 声音 中检查输入设备和音量，并确认设备连接与麦克风权限。如控件不可用，请更新 App 并刷新页面。
分享时把语音软件的声音也传出去了	Windows App 屏幕采集可选择排除应用声音；该功能不消除扬声器被麦克风收音产生的回声。
网页能打开，画面连不上	重新连接 按钮可用时先点击，否则刷新观看页。仍然失败时，查看 画面连接排查。
开启了 WebRTC 或 IP 泄露保护	按浏览器 WebRTC 设置检查是否阻止了媒体连接。
校园网或受限网络连不上	先用手机热点对照，再考虑启用 SFU 的自建站点。
画面反复模糊、卡顿或中断	先分清哪些观众受影响，再按画质与中断排查操作。
手机全屏仍有黑边，或全屏按钮无效	画面会保持原始比例，可尝试横屏；使用播放栏的 全屏观看 按钮，系统视频全屏由浏览器提供。详见观看操作。
休眠或挂起后分享中断	唤醒设备，回到分享标签页，必要时重新开始分享。浏览器或系统挂起可能中断采集和播放。

反馈问题时，请附上版本、系统与浏览器、预期结果和复现步骤。 诊断与导出 说明如何收集本地报告，以及分享前需要检查哪些内容。

选源后无法开始分享

电视下方的错误图标说明当前失败；点击可打开排查面板，查看建议、复制失败信息， 或开启网页诊断。复制内容包含网页版本、提示和错误编号，不包含邀请链接或来源名称。

• App 连接断开或请求超时：确认 App 仍在运行且可以响应，从 App 打开当前站点后刷新。 浏览器询问本地网络权限时允许访问。超时只说明请求未及时完成，不能据此认定显卡故障。
• App 未能启动所选来源：先换一个普通窗口或屏幕；再对照「浏览器」选源。 Windows 上可试「自动」或 VP8，后续按显卡排查操作。
• 浏览器无法读取来源或缺少权限：保持来源打开，允许系统录屏权限，回到分享页重新选源。 摄像头还需检查设备是否正被其他程序独占。
• 媒体连接失败：检查浏览器 WebRTC 设置和本地网络权限。 创建房间返回 403 则按下节检查站点配置。

恢复后不必继续排查。仍然失败时，先开启诊断，再重现一次：网页按钮只收集浏览器报告； 使用 App 时也请在模式选择页开启「诊断启动」，随后在终端按 D 导出 App 报告。 将同一次尝试的报告与复制的失败信息一起反馈，并说明所选来源类型。 没有报告时仍可反馈；单独一张「分享失败」截图通常无法确定采集、编码或连接中的具体原因。 日志保存在本机，分享前请检查其中的私人信息。操作细节见诊断与导出。

创建房间返回 403

浏览器访问的网址不在服务端允许的范围内时，页面可能正常打开，但创建房间会被拒绝。 站点管理员可以按以下步骤检查：

1. 将 PUBLIC_BASE_URL 设为浏览器访问的站点地址，包含协议和非默认端口，不带路径。
2. ALLOWED_ORIGINS 不设置或留空时使用上述地址；需要多个地址时，用英文逗号列出全部 可信地址。复制过配置示例的话，检查这里是否仍残留 http://localhost:8787。
3. 重启 VeScreen；使用 Compose 时运行 docker compose up -d 重建容器。刷新网页后重试。

配置正确但响应仍是 Origin not allowed 时，检查反向代理是否保留浏览器的 Origin 请求头。如果 403 来自代理或 WAF 本身，则应查看对应日志，不要通过关闭来源校验来绕过。 配置方法见 Server 部署指南。

App 找不到窗口或屏幕

在分享画面的这台电脑上保持 VeScreen App 运行，并从 App 打开当前站点。 使用已部署的站点时，在 App 的 站点 模式中填写该站点地址。 浏览器询问本地网络权限时允许访问，再刷新来源列表；如果之前拒绝过，先检查当前站点的浏览器权限。

选源器会区分以下情况：

提示	处理方法
未能连接 VeScreen App	确认 App 正在运行，且通过 App 打开了当前站点。关闭其他正在使用 App 的闲置 VeScreen 标签页后刷新列表；最多两个页面可以同时使用 App 的原生采集或收看功能。
VeScreen App 与当前页面不兼容	更新 VeScreen App 并刷新页面。
VeScreen App 采集功能当前不可用	查看 App 诊断信息中的采集和编码能力，检查编码设置，或使用浏览器采集。
未能读取 App 的窗口和屏幕列表	刷新重试；若持续失败，请导出同一次尝试的 App 和网页诊断报告。
暂无可用来源	已成功读取列表，但当前分类没有可选来源，可以查看其他分类。

本地网络权限用于让网页连接 App，与下文的 WebRTC 媒体设置不同。 仅凭 App 未连接，不能确定是权限被拒绝。

Windows 上 H264 分享失败

选中窗口或屏幕后回到未分享状态，或出现「启动分享失败」，可能涉及采集、编码或网页与 App 之间的媒体连接，不能仅凭提示确定是显卡驱动问题。

1. 用同一来源对比编码。 在 设置 → 连接与编码 中，将视频编码从 H264 改为 自动 或 VP8，重新开始分享。如果 VP8 正常，可以先用它，再排查 H264 路径。
2. 更新后重启。 更新 VeScreen App 和 Chrome，并从电脑或显卡厂商的官方网站安装适合本机的 显卡驱动。双显卡笔记本应检查两块显卡的驱动，安装后重启电脑。
3. Chrome 检查图形加速和首选显卡。 在 Chrome 设置 → 系统 中检查「使用图形加速 （如果可用）」，此前关闭的话可开启并重启 Chrome（Google 设置说明）。 Windows 多显卡电脑还可以进入 设置 → 系统 → 屏幕 → 显示卡（图形）， 选择或添加 Chrome（chrome.exe），在 选项 中选择 高性能 并保存。 完全退出 Chrome 后重新打开再试；没有改善就恢复 让 Windows 决定 （微软显卡设置说明，英文）。

首选显卡是浏览器侧的排查项，不保证 H264 一定可用。VeScreen App 会单独选择原生编码器， 修改 Chrome 的首选显卡不会指定 App 的采集显卡。App 采集仍失败时，保留上述编码对照结果， 导出同一次尝试的 App 与网页诊断报告，并附上显卡型号、驱动版本、选源方式和 VP8 是否正常。 两种编码都失败时，也检查下方的 WebRTC 限制。

游戏黑屏或进入游戏后停止分享

先确认当前分享的是游戏窗口或游戏所在的屏幕，再尝试游戏的无边框窗口模式。 对照分享一个普通窗口，并在 App 选源与 浏览器 选源之间比较。 受保护的内容可能无法采集；某个游戏失败不代表所有来源都不可用。

如果进入游戏后 VeScreen 退回未分享状态，查看电视下方的失败原因，按分享启动排查操作。 反馈时附上游戏名称、窗口模式、选源方式、编码器和同一次尝试的 App／网页报告。 不要仅凭「没有画面」确定为编码故障。

HDR 画面过亮或颜色发白

Windows App 的 程序 / 窗口 和 屏幕 采集会将 HDR 转成 SDR，再分享给观众。 浏览器 选源由浏览器负责采集，部分 HDR 来源可能过曝；这是当前的已知限制。 可改用 App 的上述分类，或在 Windows 显示设置中暂时关闭 HDR 后重新选源。 提高分辨率或码率无法恢复已经丢失的亮部细节。

仍然异常时，请说明使用的是哪种选源方式、是否开启 HDR、显卡和显示器型号， 并附上源画面与观众画面的对照。技术背景见 HDR 采集说明（英文）。

Windows 分享时出现黄框

Windows 用黄色边框标出正在采集的窗口或屏幕。在支持的 Windows 版本上， App 选源器提供 显示采集边框 开关，默认关闭；系统权限或其他正在进行的采集 仍可能要求显示边框。Windows 10 的采集接口没有这个开关。

Windows 11 关闭开关后仍有黄框

1. 从 VeScreen 的 程序 / 窗口 或 屏幕 列表选源，保持 显示采集边框 关闭。 通过浏览器选源时，采集标识由浏览器管理。
2. 停止其他软件或标签页对同一窗口、屏幕的采集，再重新开始分享。
3. 如果之前拒绝了无边框采集权限，在 Windows 隐私设置中检查 屏幕截图边框。 支持该设置页的系统也可以按 Win+R，输入 ms-settings:privacy-graphicscapturewithoutborder 打开。

Windows 需要用户授权；其他采集要求显示边框时，边框仍会保留 （微软接口说明，英文）。 仍未解决时，反馈中请附上 Windows 版本、选源方式和 App 诊断报告。

Windows 10 可选处理方法

DWM Custom Projection Border 是适用于 x64（64 位）Windows 的 Windhawk 第三方模组，可以在保持原有采集方式的情况下隐藏黄框。 它会修改 Windows 桌面合成器的行为，也会影响其他软件的采集提示。 作者提供了 Windows 10 21H2 的效果示例；以下步骤尚未在 Windows 10 设备上配合 VeScreen 实测。

1. 从官方网站安装 Windhawk。
2. 打开 Windhawk 全局的 设置 → 高级设置 → 更多高级设置， 在 包含的进程列表（Process inclusion list） 中追加一行 dwm.exe 并保存，保留已有条目。
3. 搜索并安装 DWM Custom Projection Border，在模组设置中开启 Disable border（关闭边框） 并保存。
4. 在 VeScreen 中停止后重新开始分享，检查黄框是否消失。

恢复原状时，禁用该模组并重新开始分享。如果 dwm.exe 这一项是专门为该模组添加的， 也可以移除。若桌面出现异常，或 Windows 更新后不再兼容，先禁用模组。

最新操作说明见模组作者说明 和 Windhawk 进程设置文档（英文）。

公网邀请创建失败或出现 1033

App 的 公网邀请 通过 Cloudflare Tunnel 提供临时网页地址。 public invitation service exited before connecting 表示辅助程序在连接完成前退出； exit status 1 本身不能说明具体原因。 Cloudflare 的 1033 说明（英文） 表示该地址当前没有可用的隧道连接。这与网页能打开、但显示「没有可用的媒体线路」是不同的问题。

1. 观众先确认链接。 请房主确认 App 仍在运行、电脑未休眠，并发送当前邀请。 App 重新启动后应使用新链接，旧地址可能失效。
2. 房主查看终端原因。 确认已完整解压 App 程序包；启动失败时，保留终端的完整错误， 开启 诊断启动 后再试。App 会在启动时限内重试提前退出的隧道进程。
3. 对照网络。 可用手机热点重试，检查 DNS、代理或防火墙是否阻止 Cloudflare Tunnel。 只调整相关规则；学校或公司的网络应联系管理员。

反复失败时可先通过在线版或已有站点分享。 反馈中请附上 App 版本、失败时间和 App 诊断报告。 如果打不开的是自建站点而非 App 的临时地址，请联系该站点管理员检查服务。

画面模糊、卡顿或中断

短时变糊可能来自网络或编码负载的自动调整；反复出现或长期不恢复时，按下面的步骤对照：

1. 确认影响范围。 是房主预览、所有观众，还是只有某位观众？记录大致时间， 以及能否自行恢复。房主预览清楚并不保证观众的连接也正常。
2. 一次调整一项。 房主可在 设置 → 画面 中先试较低的分辨率或帧率， 检查游戏运行时 CPU／GPU 是否接近满载；受影响的观众可用另一浏览器或手机热点对照。 将码率调高不一定有帮助。
3. 保留问题发生时的报告。 在房主和受影响的观众页面开启诊断后重现， App 采集还需 App 报告。画面持续不恢复时可尝试 重新连接；请先导出报告再刷新页面。

如果分享已自动停止，查看电视下方的具体原因，并按分享启动排查操作； 如果仍在分享但观众看不到画面，继续查看下方的连接排查。

画面连接不上

没有可用的媒体线路 表示 VeScreen 还没有找到能把画面送到你设备上的连接。 网页和媒体使用不同的连接，所以可能出现网页能打开、画面却连不上的情况。

NAT（网络地址转换）让多台设备共用一个上网地址。不同路由器和运营商对地址转换、 外部数据进入的规则不同，有些组合会让设备难以直连。防火墙和浏览器策略也可能阻止媒体连接， 仅凭这条提示还不能确定具体原因。

可以依次尝试，画面恢复后就不必继续：

1. 重新尝试观看连接。 如果 重新连接 可用，先点击；按钮不可用或没有效果时， 刷新观看页或重新打开邀请链接。每次等连接尝试结束，重试一两次即可；反复刷新无法解除网络限制。
2. 检查浏览器的 WebRTC 设置。 浏览器设置、VPN 或隐私扩展可能阻止媒体连接， 即使网页本身能打开；房主和观众都会受影响，具体操作见下方的 WebRTC 排查。
3. 换个网络测试。 例如试用手机热点。如果使用了 VPN 或代理，检查其 UDP 策略；受管理的网络请联系管理员。
4. 开启可用的 IPv6。 先确认宽带、路由器和设备都支持。连接双方都有可用 IPv6 时， VeScreen 可以多尝试一条直连路径；它仍受防火墙规则约束，同时保留 IPv4 即可。
5. 检查自己管理的路由器。 在可信家庭网络中，路由器支持的 UPnP、PCP 或 NAT-PMP 可以让 App 的原生媒体连接申请端口映射；纯浏览器采集不会申请这些映射。 如果光猫和路由器都在做 NAT，可按对应型号的桥接或 AP 模式说明减少一层。 运营商共享公网地址（CGNAT）位于路由器上游，需要向运营商咨询公网 IPv4 或 IPv6 服务。 修改路由器工作模式前，先备份配置。
6. 请另一网络的朋友加入。 如果对方能正常看到画面，且有余力转发，VeScreen 可能经由这位观众 把画面送到你这里。线路由 VeScreen 自动选择，能否帮上忙取决于这些连接是否可用。
7. 使用有媒体兜底的站点。 管理员需要先启用 SFU 转发。如果页面提供 隐私模式， 房主应在分享前关闭；配置为 服务器转发 的站点已经强制使用 SFU。 公开站点 demo.piik.tv 和 App 的 公网邀请 模式均没有 SFU 兜底。 有服务器的用户也可以按 部署指南 配置，属于进阶操作。 目前 P2P 和 SFU 媒体都使用 UDP；网络完全禁止 UDP 时，仍需换网络或由管理员放行。

不同型号的路由器菜单会有差异，可参考厂商的 IPv6 条件说明、 UPnP 说明 和 双重 NAT 调整示例（英文）。 想了解连接机制，可以阅读 WebRTC 官方说明（英文）。

仍然失败时，收集出现问题的观众端与房主端同一次尝试的 诊断报告，反馈时附上发生时间、VeScreen 版本和所用网络类型。

浏览器限制了 WebRTC

VeScreen 通过 WebRTC 传输画面和声音。禁用 WebRTC 或禁止未经代理的 UDP，可能使观众收不到画面， 甚至阻断本机网页与 App 之间的媒体连接；能选到来源并不代表这条连接可用。 仅隐藏本机 IP 地址不一定会阻止 WebRTC。

1. 使用默认设置、未安装 VPN 或隐私扩展的浏览器配置打开同一邀请进行对照。 如果可以连接，再检查原配置中的 WebRTC 或 IP 泄露保护选项。
2. 恢复允许 WebRTC UDP 的策略。disable_non_proxied_udp 表示限制未经代理的 UDP， 可以先与浏览器默认策略对比。Vivaldi 的选项位于 设置 → 隐私和安全 → WebRTC IP 处理， 开启 广播 IP 以获得最佳 WebRTC 性能。Chrome 中的扩展也可能控制该策略，即使浏览器没有显式开关。
3. 修改后刷新受影响的 VeScreen 页面，重新尝试分享或观看。由学校或公司统一管理的设置，请联系管理员检查。

允许这些连接可能向 WebRTC 对端暴露网络地址，只调整相关选项即可。 参考 Chrome 策略说明 和 Vivaldi 隐私设置（英文）。

校园网或严格 NAT

校园网并不一定无法使用 VeScreen，但多人共用出口、严格的防火墙策略可能让直连更困难。 先用手机热点打开同一邀请对照；热点可用时，优先排查原网络的限制。

经常需要使用的话，建议考虑 自建 VeScreen 站点并启用 SFU 媒体转发，让直连失败时有服务器路线。 按部署指南配置公网地址并放行所需 UDP 端口。 房主随后可通过 App 的 站点 模式打开新站点，并发送该站点生成的邀请链接。

公开 Demo 和 App 的公网邀请模式只有 P2P。SFU 同样需要 UDP 可用；如果网络完全禁止 UDP， 仍需换网络或联系管理员放行，单独搭建服务器不能解除这类限制。

想为朋友搭一个站点？从 部署指南 开始。 其他指南可在 文档中心 找到。