故障排除：浏览器

修复嵌入式浏览器面板的常见问题。

本地应用无法加载

症状： 你在浏览器面板中导航到 http://localhost:3000 但看到连接错误或空白页。

修复：

  • 确保开发服务器确实在运行。 检查终端 —— 查找启动消息（例如来自 Next.js 的 ready on http://localhost:3000，或来自 Vite 的 Local: http://localhost:5173/）。如果服务器未运行，使用你通常的命令启动它（npm run dev、yarn dev 等）。
  • 尝试 127.0.0.1 而不是 localhost。 某些系统解析 localhost 的方式与预期不同。在 URL 栏中将 localhost 替换为 127.0.0.1 —— 例如 http://127.0.0.1:3000。
  • Content-Security-Policy 请求头。 如果你的应用设置了严格的 CSP 请求头以防止嵌入到 webview 中，浏览器面板将拒绝显示它。在开发模式下，你可以放宽这些请求头。例如，在 Next.js 中，你可以在 next.config.js 中仅为本地开发移除或放宽 frame-ancestors 指令。

浏览器面板高度折叠

症状： 浏览器面板缩小为一条细带，你无法看到应用。

修复： 拖动 面板分隔线（浏览器面板与上方或下方面板之间的细条）调整浏览器大小。向上拖动它为浏览器提供更多垂直空间。

如果你想要浏览器占据尽可能多的空间，使用 全屏模式：按 Cmd+Shift+F（或 Windows/Linux 上的 Ctrl+Shift+F）将浏览器面板扩展到填充窗口。再次按相同的快捷键返回正常布局。

视频或音频无法播放

嵌入式浏览器面板不支持所有媒体编解码器。某些视频格式或音频流可能无法在面板内播放。

修复： 在浏览器面板内任意位置右键点击并选择 Open in External Browser。这会在系统默认浏览器（Safari、Chrome、Firefox 等）中打开当前 URL，具有完整的编解码器支持。将此用于媒体密集型页面、视频播放器或需要浏览器插件的任何内容。

页面显示空白/白屏

空白白屏通常意味着页面已加载，但在显示任何内容之前 JavaScript 中出了什么问题。

修复：

  1. 点击浏览器面板工具栏中的 DevTools 按钮（扳手或 </> 图标）。
  2. 打开 Console 标签。
  3. 查找红色错误消息。

本地开发最常见的原因是 CORS 错误 —— 你的前端正在向本地 API 发出请求，而 API 拒绝它，因为请求来自 webview 来源而不是 localhost。要在开发中修复此问题，配置你的 API 服务器允许所有来源：

  • Express / Node： 使用 cors 包添加 app.use(cors())。
  • FastAPI： 添加 CORSMiddleware 并设置 allow_origins=["*"] 用于开发。
  • Next.js API 路由： 在路由处理程序的响应头中添加 Access-Control-Allow-Origin: *。

记得在部署到生产环境之前再次限制来源。