GitHub Codespaces自动端口转发URL不含preview无法正常访问的原因

问题现象 #

• 配置了适配GitHub Codespaces的Docker Compose环境，部署完成后自动生成的端口转发URL访问时会触发文件下载，无法正常跳转至Web服务器；但添加preview后缀的URL可正常访问。
• 无效URL：https://refactored-spoon-jqj97wvp4qcqv4g-80.app.github.dev/
• 有效URL：https://refactored-spoon-jqj97wvp4qcqv4g-80.preview.app.github.dev/
• 相关配置目录：仓库中的.devcontainer

原因分析 #

GitHub Codespaces的端口转发存在两种URL模式：

1. 无preview后缀的代理URL：属于原始流量转发模式，默认适配API服务、非Web类应用。如果你的Web服务器返回的Content-TypeHTTP头设置错误（比如未指定text/html，而是返回了二进制流类型），浏览器会将响应识别为可下载文件，触发下载操作。此外该模式不会额外处理HTTP重定向或MIME类型适配，导致网页无法正常渲染。
2. 带preview后缀的预览URL：属于GitHub优化后的网页预览模式，代理层会自动处理HTTP请求的Content-Type头、重定向等逻辑，确保浏览器正确识别网页内容，因此能正常访问。

为什么自动生成的是无preview的URL？ #

默认情况下，Codespaces检测到端口开放后，会优先创建原始流量代理类型的URL（不带preview）。若要默认生成preview后缀的URL，可通过两种方式设置：

• 手动切换：在Codespaces的「端口」面板中，找到对应端口（如80）的菜单，选择「Change visibility」→「Public preview」，生成的URL将自动添加preview后缀。
• 配置指定：在.devcontainer/devcontainer.json中添加端口配置，指定默认启用预览模式：

"portsAttributes": {
  "80": {
    "label": "Web Server",
    "visibility": "public",
    "preview": true
  }
}

内容的提问来源于stack exchange，提问作者Jon Erickson