Free, open-source screen sharing for private live streams with friends. Watch together in a browser or self-host Piik. 免费开源的私密屏幕共享,支持游戏直播、一起看电影与自部署。
outline: 2
问题排查
按症状查找下方说明,依次尝试,恢复正常后就不必继续。 仍有问题时,请在刷新前收集诊断报告。
常见问题
从最先出问题的地方开始:
| 你看到什么 | 先查哪里 |
|---|---|
| App 打不开,或邀请网页无法访问 | 打开 App 与加入房间。 |
| 没有选源器,或选好来源后无法开播 | 来源与采集检查。 |
| 网页能打开,但画面连接不上 | 媒体连接。 |
| 画面模糊或卡顿 | 画质检查。 |
| 手机找不到全屏或播控按钮 | 全屏与播控。 |
| 有画面,但听不到游戏/影片声音 | 来源声音。 |
| 听不到朋友,或无法开麦 | 房间语音与浏览器权限。 |
| 手柄没有响应 | 手柄排查。 |
对应症状的简单检查无效后,再看进阶网络排查。每次只改一项,方便对照。
打开 App 与加入房间
启动失败 · 安卓安装 · macOS 打不开 · 公网邀请 / 1033 · 本地邀请 · 本地证书 · 房间号 · 创建房间 403
App 启动失败或没有打开网页
- 查看启动页面和终端中的原因。App 仍在运行时,可复制显示的地址,在浏览器中打开。
- 本地模式列出多个地址时,选择朋友能访问的网卡和 IP,见本地邀请排查。
- 仍然失败时,开启 诊断启动 后重试,保留完整错误和 App 报告。
安卓 APK 无法安装
按 App 安装步骤下载 APK。 安卓提示时,允许本次使用的浏览器或文件管理器安装下载的 APK。
如果安装提示软件包冲突或签名不一致,且之前安装过测试版,请先卸载测试版,再安装正式 APK。 测试版与正式版使用不同的签名密钥。卸载会清除 App 设置,包括已授权站点和收藏的启动站点; 浏览器设置独立保存。之后的正式版更新可以覆盖安装。
macOS 提示已损坏或无法验证开发者
当前 Mac 版本未进行 Developer ID 签名和 Apple 公证。首次打开时,先校验下载文件,再为这个 App 放行:
若 macOS 提示恶意软件、「会损坏你的电脑」,或自动将 App 移到废纸篓, 请保留完整提示和下载链接反馈,不要使用下方的隔离标记命令。
从项目 Releases 下载对应的 Mac ZIP,核对同一版本公布的 SHA-256。 在终端运行
shasum -a256 ~/Downloads/piik-app-darwin-arm64.zip; Intel Mac 将文件名中的arm64换为amd64。校验不一致时应重新下载,不要绕过警告。把完整的
Piik App.app移到「应用程序」,尝试打开后,在 系统设置 → 隐私与安全性 → 仍要打开 中确认。 具体步骤见 Apple 首次打开说明。如果没有「仍要打开」,且已确认官方 ZIP 的校验值一致,可在终端仅移除这个 App 的下载隔离标记,再重新打开:
xattr -dr com.apple.quarantine "/Applications/Piik App.app"
保留在其他位置时,换成 App 的实际路径。保持系统整体安全检查开启。
公网邀请创建失败或出现 1033
App 的 公网邀请 通过 Cloudflare Tunnel 提供临时网页地址。
错误 1033(英文)
表示隧道已断开。出现 public invitation service exited before connecting 或 exit status 1 时,
查看后续的详细错误,按下方步骤排查。
- 观众先确认链接。 请房主确认 App 仍在运行、电脑未休眠,并发送当前邀请。 App 重新启动后应使用新链接,旧地址可能失效。
- 房主查看错误详情。 确认已完整解压 App 程序包;保留启动页面或终端的完整错误, 包括退出码后的详细信息。开启 诊断启动 后再试。
- 对照网络。 可用手机热点重试,检查 DNS、代理或防火墙是否阻止 Cloudflare Tunnel。 只调整相关规则;学校或公司的网络应联系管理员。
进阶:隧道错误、代理与 7844 端口
使用代理时,请确认它实际覆盖 cloudflared 进程。仅开启浏览器代理或设置
HTTP_PROXY/HTTPS_PROXY,不会让当前随包的隧道程序自动走代理。
错误详情可以帮助区分失败的环节:
| 错误中出现 | 检查什么 |
|---|---|
failed to request quick Tunnel、api.trycloudflare.com |
临时地址申请失败。查看后面的具体原因:域名解析错误检查 DNS;连接超时检查 HTTPS 出站连接、代理或服务状态。 |
QUIC 超时、dial tcp ...:7844 或 TLS handshake with edge |
到 Cloudflare 隧道节点的连接失败。检查 cloudflared 的出站规则,包括代理或游戏加速器是否影响该连接。 |
Piik 在 QUIC(UDP)失败后会尝试 HTTP/2(TCP),请允许两者使用出站端口 7844。
具体要求见 Cloudflare 连接排查(英文),
无需在路由器上开放入站端口。
暂时绕过公网邀请: 保持 App 运行,打开在线版或其他可访问站点, 授权 App 采集,再发送新站点的房间邀请。 在线版无需站点口令,媒体使用 P2P;需要服务器转发时,选择启用 SFU 的站点。 网页能打开但画面连不上时,转到画面连接排查。 如果打不开的是自建站点而非 App 的临时地址,请联系该站点管理员检查服务。
本地邀请打不开
浏览器连接超时、Piik 页面打不开时,先检查到房主 App 的访问:
- 保持房主 App 运行,在 本地房间 选择朋友能访问的网卡地址,发送完整邀请链接。 两台设备需处于可互访的局域网或同一个虚拟局域网;访客 Wi-Fi 可能隔离设备。
- Windows 房主打开 Windows 安全中心 → 防火墙和网络保护 → 允许应用通过防火墙,
检查当前运行的
piik-app.exe,允许所用的网络类型。虚拟网卡可能被识别为 公用网络; 需要更小范围时,可在高级规则中限定该虚拟网卡和网段。 - 更新后换了解压目录,请更新仍指向旧文件的防火墙规则;需要时手动添加当前 App,保持防火墙开启。
App 提示 本地端口不可用 时,先关闭占用它的旧 Piik 实例。如果其他程序需要这个端口,
可用 --port 9876 启动 Piik,再发送新生成的邀请。网页和本地 STUN 端口都需要可用;
只修改链接里的端口不会改变服务的实际位置。
放行操作可能需要管理员权限,参阅 Microsoft 说明。 网页能打开但画面连不上时,再按画面连接排查检查媒体线路。
本地 HTTPS 证书提示
Piik App 的 本地房间,以及启用 TLS_SELF_SIGNED=true 的服务端,会自行生成本地证书。
它没有经过公共证书机构签发,因此浏览器会先显示证书警告。
- 确认网址与房主准备分享的地址一致。
- 打开警告页的证书详情,将 SHA-256 指纹 与房主 App 终端中的 本地证书 · SHA-256, 或服务端启动时的 HTTPS certificate 信息对照。异地使用时,可通过平时信任的聊天渠道向房主核对。
- 指纹一致后,使用浏览器提供的 高级 → 继续访问;进入页面后,再正常允许麦克风或申请远控。
重启 App/服务端会更换临时证书,新指纹需要重新确认。App 不保存证书文件,也不安装系统受信任证书。 不要全局关闭浏览器的安全检查。如果浏览器不允许接受例外,请改用该设备已信任证书的 HTTPS 站点; 管理员可参阅 HTTPS 部署说明。
以上只适用于预期中的本地自签名证书;普通公网 HTTPS 站点突然出现证书警告时,应让管理员排查原因。
房间号无法使用
先打开房主最新的完整邀请链接。房间号只在原 Piik 站点有效;站点开启空房间回收时, 旧房间也可能已被回收,由房主重新创建即可。参阅加入房间。
站点房间号已用满时,稍后重试或使用其他 Piik 站点。管理员可配置 空房间回收以收回闲置号码。
创建房间返回 403
浏览器访问的网址不在服务端允许的范围内时,页面可能正常打开,但创建房间会被拒绝。 站点管理员可以按以下步骤检查:
- 将
PUBLIC_BASE_URL设为浏览器访问的站点地址,包含协议和非默认端口,不带路径。 ALLOWED_ORIGINS不设置或留空时使用上述地址;需要多个地址时,用英文逗号列出全部 可信地址。复制过配置示例的话,检查这里是否仍残留http://localhost:8787。- 重启 Piik;使用 Compose 时运行
docker compose up -d重建容器。刷新网页后重试。
配置正确但响应仍是 Origin not allowed 时,检查反向代理是否保留浏览器的 Origin
请求头。如果 403 来自代理或 WAF 本身,则应查看对应日志,不要通过关闭来源校验来绕过。
配置方法见 Server 部署指南。
开始分享
没有选源器 · 找不到窗口 · 选源后失败 · H264 失败
分享失败时,点击电视下方的错误图标,查看原因、当前阶段的检查和 复制失败信息;按提示检查后再重试。

示例 App 采集错误。实际原因和检查项取决于失败阶段。
没有屏幕选择弹窗
按系统提示允许录制屏幕。浏览器屏幕采集需要 HTTPS 或 localhost,请在电脑上尝试分享。
在选源器中选择 浏览器 → 选择画面,打开浏览器的屏幕、窗口或标签页选择弹窗。
App 来源缺失则按下节操作。
App 找不到窗口或屏幕
在分享电脑上保持 App 运行,点击站点顶部的 App,在本机确认页核对站点并授权。 浏览器询问本地网络权限时允许访问,再刷新来源列表;之前拒绝过则先检查当前站点的权限。
选源器会区分以下情况:
| 提示 | 处理方法 |
|---|---|
| 未能连接 Piik App | 确认 App 正在运行,且当前站点已获得授权。关闭其他正在使用 App 的闲置 Piik 标签页后刷新列表;最多两个页面可以同时使用 App 的原生采集或收看功能。 |
| Piik App 与当前页面不兼容 | 更新 Piik App 并刷新页面。 |
| Piik App 采集功能当前不可用 | 查看 App 诊断信息中的采集和编码能力,检查编码设置,或使用浏览器采集。 |
| 未能读取 App 的窗口和屏幕列表 | 刷新重试;若持续失败,请导出同一次尝试的 App 和网页诊断报告。 |
| 暂无可用来源 | 已成功读取列表,但当前分类没有可选来源,可以查看其他分类。 |
本地网络权限用于让网页连接 App。连接后媒体仍失败时,检查WebRTC 设置。
选源后无法开始分享
点击电视下方的错误图标,可查看排查建议、复制失败信息,或开启网页诊断。
- App 连接断开或请求超时:确认 App 仍在运行且可以响应,点击站点顶部的 App 完成连接。 浏览器询问本地网络权限时允许访问。
- App 未能启动所选来源:先换一个普通窗口或屏幕;再对照「浏览器」选源。 Windows 上可试「自动」或 VP8,后续按显卡排查操作。
- 浏览器无法读取来源或缺少权限:保持来源打开,允许系统录屏权限,回到分享页重新选源。 摄像头还需检查设备是否正被其他程序独占。
- 媒体连接失败:检查浏览器 WebRTC 设置和本地网络权限。 创建房间返回 403 则检查站点配置。
仍然失败时,收集同一次尝试的网页与 App 报告,附上复制的失败信息和所选来源类型。
Windows 上 H264 分享失败
- 用同一来源对比编码。 在 分享设置 → 画面 → 画面细调 中,将视频编码从 H264 改为 自动 或 VP8,重新开始分享。如果 VP8 正常,可以先用它,再排查 H264 路径。
- 更新后重启。 更新 Piik App 和 Chrome,并从电脑或显卡厂商的官方网站安装适合本机的 显卡驱动。双显卡笔记本应检查两块显卡的驱动,安装后重启电脑。
- Chrome 检查图形加速和首选显卡。 在 Chrome 设置 → 系统 中检查「使用图形加速
(如果可用)」,此前关闭的话可开启并重启 Chrome(Google 设置说明)。
Windows 多显卡电脑还可以进入 设置 → 系统 → 屏幕 → 显示卡(图形),
选择或添加 Chrome(
chrome.exe),在 选项 中选择 高性能 并保存。 完全退出 Chrome 后重新打开再试;没有改善就恢复 让 Windows 决定 (微软显卡设置说明,英文)。
Chrome 的首选显卡设置用于浏览器采集,Piik App 会单独选择原生编码器。 仍然失败时,收集报告并保留编码对照结果;两种编码都失败时,也检查 WebRTC 限制。
画面与播放
画面连不上 · 模糊 / 卡顿 · 游戏黑屏 · HDR 发白 · 采集黄框 · 全屏 / 休眠
画面连接不上
没有可用的媒体线路 表示 Piik 尚未找到将画面送到你设备的连接。 依次检查观看连接、浏览器策略与网络:
- 重新尝试观看连接。 重新连接 可用时先点击,否则刷新观看页或重新打开邀请。 每次等连接尝试结束,重试一两次即可;反复刷新无法解除网络限制。
- 检查浏览器 WebRTC 设置。 浏览器设置、VPN 或隐私扩展可能阻止房主或观众的媒体连接, 具体操作见 WebRTC 排查。
- 换个网络测试。 例如试用手机热点。使用 VPN 或代理时,检查其 UDP 策略;受管理的网络请联系管理员。
- 请另一网络的朋友加入。 对方能正常看画面且有余力转发时,Piik 可能经由这位观众送到你这里。 线路由 Piik 自动选择,能否帮上忙取决于这些连接是否可用。
仍然失败时,继续进阶网络排查,并收集房主与受影响观众同一次尝试的报告。
画面模糊、卡顿或中断
短时变糊可能来自网络或编码负载的自动调整;反复出现或长期不恢复时,按下面的步骤对照:
- 确认影响范围。 是房主预览、所有观众,还是只有某位观众?记录大致时间, 以及能否自行恢复。
- 一次调整一项。 房主可在 分享设置 → 画面 中先试较低的分辨率或帧率, 检查游戏运行时 CPU/GPU 是否接近满载;受影响的观众可用另一浏览器或手机热点对照。 将码率调高不一定有帮助。
- 查看实际编码。 展开房主的 连接详情,查看 视频编码。Windows 上, 「自动」选择 VP8 可能是 H264 不可用、未能完成检测,或检测未达到所选帧率; 软件编码会与游戏争用 CPU。使用「浏览器」选源时,可按显卡排查 检查图形设置,或对照 App 的窗口/屏幕采集。App 会独立尝试可用的硬件编码器。 H264 检测未通过时,继续使用「自动」或 VP8。
- 保留问题发生时的报告。 按反馈说明收集房主和受影响观众的报告, App 采集还需 App 报告。画面持续不恢复时可尝试 重新连接;请先导出报告再刷新页面。
如果分享已自动停止,查看电视下方的具体原因,并按分享启动排查操作; 如果仍在分享但观众看不到画面,按连接排查操作。
游戏黑屏或进入游戏后停止分享
先确认当前分享的是游戏窗口或游戏所在的屏幕,再尝试游戏的无边框窗口模式。 对照分享一个普通窗口,并在 App 选源与 浏览器 选源之间比较。 受保护的内容可能无法采集。
如果进入游戏后 Piik 退回未分享状态,查看电视下方的失败原因,按分享启动排查操作。 反馈报告中请附上游戏名称和窗口模式。
HDR 画面过亮或颜色发白
Windows App 的 程序 / 窗口 和 屏幕 采集会将 HDR 转成 SDR,再分享给观众。 浏览器 选源由浏览器负责采集,部分 HDR 来源可能过曝。 可改用 App 的上述分类,或在 Windows 显示设置中暂时关闭 HDR 后重新选源。 提高分辨率或码率无法恢复已经丢失的亮部细节。
仍然异常时,请附上 HDR 设置、显卡/显示器型号及源画面与观众画面的对照。 技术背景见 HDR 采集说明(英文)。
Windows 分享时出现黄框
Windows 用黄色边框标出正在采集的窗口或屏幕。App 检测到采集能力支持时, 选源器会提供 显示采集边框 开关,默认关闭;系统权限或其他正在进行的采集 仍可能要求显示边框。Windows 10 的采集接口没有这个开关。
Windows 11 关闭开关后仍有黄框
- 从 Piik 的 程序 / 窗口 或 屏幕 列表选源,保持 显示采集边框 关闭。 通过浏览器选源时,采集标识由浏览器管理。
- 停止其他软件或标签页对同一窗口、屏幕的采集,再重新开始分享。
- 如果之前拒绝了无边框采集权限,在 Windows 隐私设置中检查 屏幕截图边框。
支持该设置页的系统也可以按 Win+R,输入
ms-settings:privacy-graphicscapturewithoutborder打开。
Windows 需要用户授权;其他采集要求显示边框时,边框仍会保留 (微软接口说明,英文)。 仍未解决时,请附上 Windows 版本和 App 报告。
进阶:Windows 10 可选处理方法
Windows 10 可选处理方法
DWM Custom Projection Border 是适用于 x64(64 位)Windows 的 Windhawk 第三方模组,可以在保持原有采集方式的情况下隐藏黄框。 它会修改 Windows 桌面合成器的行为,也会影响其他软件的采集提示。 使用前请核对模组要求的 Windows 版本。
- 从官方网站安装 Windhawk。
- 打开 Windhawk 全局的 设置 → 高级设置 → 更多高级设置,
在 包含的进程列表(Process inclusion list) 中追加一行
dwm.exe并保存,保留已有条目。 - 搜索并安装 DWM Custom Projection Border,在模组设置中开启 Disable border(关闭边框) 并保存。
- 在 Piik 中停止后重新开始分享,检查黄框是否消失。
恢复原状时,禁用该模组并重新开始分享。如果 dwm.exe 这一项是专门为该模组添加的,
也可以移除。若桌面出现异常,或 Windows 更新后不再兼容,先禁用模组。
最新操作说明见模组作者说明 和 Windhawk 进程设置文档(英文)。
全屏或休眠后播放异常
- 播控按钮隐藏了: 轻点画面即可重新呼出;正在远控时,使用电视底边的抽屉拉手。
- 没有全屏按钮或点击失败: 将邀请链接复制到独立浏览器打开,例如安卓 Chrome 或 iPhone Safari,避免使用聊天软件的内置浏览器。不支持系统全屏时,可用 剧场模式 放大网页内的画面。
- 全屏后 Piik 播控不见了: 浏览器进入了自带的视频播放器。退出全屏、改用 剧场模式, 即可保留 Piik 播控、弹幕和远控操作。
- 手机全屏仍有黑边: 画面默认保持原始比例,可尝试横屏,或用播控上的 切换画面适配 切换 等比铺满 或 拉伸铺满。如果已进入浏览器自带的视频播放器,先退出全屏再使用 Piik 的画面适配。见观看操作。
- 休眠或挂起后分享中断: 唤醒设备,回到分享标签页,必要时重新开始分享。 浏览器或系统挂起可能中断采集和播放。
声音与浏览器权限
来源声音 · 房间语音 · 回声 / 多余声音 · 麦克风 / 远控权限
有画面但没有来源声音
- 取消视频静音,并检查播放音量。
- 房主应选择支持分享声音的来源,并在选源器中打开声音;可用声音取决于来源和平台。
- 摄像头画面与麦克风输入分别选择。内置麦克风或 OBS 音频的用法,见摄像头与音频输入。
听不到说话声
如果房主使用 分享麦克风,先检查画面的来源声音, 并让房主检查 分享设置 → 声音。房间语音则按以下步骤排查:
- 双方都加入 互动 → 语音,由房主先选择 开启房间语音。 加入只开始收听,每位发言者还需主动打开自己的麦克风。
- 发言者检查浏览器的麦克风权限,以及 语音设置 中的输入设备和音量。
使用麦克风需要 HTTPS 或
localhost。 - 检查自己是否暂停收听或将对方本地静音。这些控制与视频静音分开;暂停收听 不会关闭自己的麦克风。
语音提示连接失败时,对照 WebRTC 设置及另一网络。 控件的使用方法见房间语音。
回声或传出了多余的应用声音
扬声器被麦克风再次收音时,可使用耳机。Windows App 屏幕采集支持 排除语音软件的来源音频,但不会消除声学回声。
虚拟麦克风在 Piik 闭麦后仍可听见时,暂时关闭 系统声音 对照。如果声音消失, 说明混音软件的播放输出也进入了来源音频。检查其播放/监听路由,或只分享需要的应用窗口音频。 Piik 的麦克风静音不会关闭这条独立来源。
无法使用麦克风或远程控制
- 打开当前 App 生成的完整 HTTPS 邀请。本地邀请应先确认证书。
普通 HTTP 内网页面可以观看、聊天和加入语音收听,但不能使用需要安全上下文的麦克风、摄像头采集和远控接口。
仅修改链接里的协议名不会开启 HTTPS;
localhost只代表当前设备。 - 麦克风不可用时,检查当前站点的浏览器权限和所选输入设备。
- 远控需更新房主 App 和站点,再刷新观众页面。房主必须使用桌面 App 窗口/屏幕采集并开启远控; 浏览器与摄像头采集不能接收远程输入。安卓可以分享屏幕,也可以作为观众控制电脑,但不能作为被控手机, 因此安卓房主页面没有开启远控的入口。随后按授权步骤操作。
浏览器不接受本地证书例外时,改用可访问的 公网邀请 或具有可信证书的 HTTPS 站点。
手柄
手柄没有响应
- 房主通过 App 分享窗口或屏幕,并开启 远程控制。
- 按支持的平台与手柄设置检查房主端。 外部驱动由房主从官方渠道安装,Piik 不附带 SDK 或驱动;安装后重新开启远程控制。
- 观众连接标准布局手柄并按一下按钮,让浏览器识别;取得远程控制权后,Piik 自动使用 浏览器标准映射下的第一个已连接手柄。保持观看页面在前台,在游戏中加入对应玩家; 手柄位已满时,断开不使用的手柄或结束该观众的远程控制。
观众只需使用浏览器,驱动检查与安装在房主电脑完成。
进阶网络排查
网页能打开但画面或语音连不上时,查看网络排查指南。按下面的情况进入对应步骤:
校园网或严格 NAT
为校园网、公司网络选择连接方案。 查看步骤。
浏览器限制了 WebRTC
同一邀请在其他浏览器里正常时,检查相关设置。 查看步骤。
STUN、IPv6 与路由器检查
查看日志、调整地址发现,或检查自己管理的路由器。 查看步骤。
可选:虚拟局域网
通过 UU 等组网工具使用本地房间。 查看步骤。
反馈问题
请附上 Piik 版本、系统与浏览器、发生时间、预期结果和复现步骤。 采集问题还需说明来源类型、编码、显卡/驱动,以及其他来源或 VP8 是否正常;网络问题说明所用网络类型。
先开启诊断,重现一次,再在刷新前导出:
- 网页: 使用页面的诊断按钮。分享失败时,电视下方的错误图标还可复制失败信息, 包含网页版本、提示和错误编号,不包含邀请链接或来源名称。
- 桌面 App 采集或远控: 还需在房主 App 模式选择页开启 诊断启动,随后在终端按
D导出 App 报告。 - 连接失败: 收集受影响观众和房主同一次尝试的报告;自部署 SFU 还需服务端报告。
报告保存在本机,分享前请检查私人信息;诊断与导出说明报告内容。 无法收集日志时,请提供完整错误文字与复现步骤。
其他指南可在文档中心找到。