如何用 .puter_site_config 为 Puter 托管的 SPA 配置 /index.html 回退让深链生效？

如何用 .puter_site_config 为 Puter 托管的 SPA 配置 /index.html 回退让深链生效？

【免费下载链接】puter🌐 The Internet Computer! Free, Open-Source, and Self-Hostable.项目地址: https://gitcode.com/GitHub_Trending/pu/puter

如果你的单页应用（SPA）直接托管在 Puter 上，客户端路由（React Router、Vue Router 或类似方案）会遇到一个典型问题：访客直接加载/dashboard时，服务器是在找一个叫/dashboard的文件，而这个文件并不存在，于是请求拿不到你的index.html，路由无从接管。Puter 的解决办法是一个可选的站点配置文件.puter_site_config：把它放在站点根目录，让“请求不匹配任何文件”这种情况改为返回index.html并带上正常的200状态码。完成配置后，深链、页面刷新和分享 URL 都能正常工作。本文基于 Site Configuration 文档给出完整的放置、配置与验证过程。

前提：站点已发布到 Puter

.puter_site_config只对已发布的站点生效，先确保你的网站已经在 Puter 上跑起来。文档提供的发布方式有：

• 在 puter.com 上右键创建文件夹、上传文件后选择Publish as Website；
• 用 Puter CLI：npm install -g @heyputer/cli后执行puter site deploy [dir] [subdomain]（CLI 目前处于 beta 0.x，命令和行为可能变化）；
• 用 GitHub Actions 的 Puter Subdomain Deploy Action 自动部署。

具体操作见 Deployments。如果你是通过代码管理站点，参见 Hosting API。

没有.puter_site_config文件时，请求一个不存在的路径会得到 Puter 默认的 404 页面——这正是要改变的默认行为。

把 .puter_site_config 放在站点根目录

文件位置只有一个要求：放在你发布的目录的顶层，和index.html平级。例如你发布的是~/Desktop/my-site，文件就应该放在~/Desktop/my-site/.puter_site_config。

两点需要知道：

• 该文件不会下发给访客。请求/.puter_site_config会像其他不存在的路径一样返回 404；
• 它是可选的，不创建该文件，站点行为与现在完全一致。

写入 SPA 回退配置

对 SPA 场景，配置内容是：当404发生时，返回/index.html这个页面，并且状态码改为200：

{ "errors": { "404": { "file": "/index.html", "status": 200 } } }

这里status是关键：errors.<code>.status是可选项，默认值就是正在处理的那个状态码——也就是说404规则如果不写status，响应就是404。只有显式写成200，浏览器拿到的是成功响应，前端路由才会接管页面。

字段参考（以文档为准）：

参考写法里出现的errors.<code>通用键（如403、500）会被接受和校验，但文档明确说明：除404外的码当前还不用于返回页面，写了也不报错，但不能依赖它们，等官方支持落地后才会生效。

可选分支——如果你只想要一个自定义 404 页面而不是 SPA 回退，同样的结构、把file指向404.html且不写status即可，响应保留真正的404状态：

{ "errors": { "404": { "file": "/404.html" } } }

两者是同一个机制的两种用法：SPA 回退要的是“假 404 + 真 200”，自定义 404 页要的是“假页面 + 真 404”。

部署后如何验证

把配置随构建产物一起重新部署（在 puter.com 上就是重新上传该文件；CLI 或 Actions 则重新执行一次部署）。验证时注意文档给出的两个特性：

1. 改动最多要等一分钟。站点配置有 60 秒缓存，刚上传完就测出“没生效”之前，先等一分钟再下结论。
2. 配置写错是被静默忽略，而不是报错。JSON 语法错误、文件超过 64 KB、或结构不符合上面的形状，Puter 都会当作文件不存在来处理——站点不会挂，但你的改动也悄无声息地不生效。所以文档的要求是：检查行为是否真的变了，而不是假设它变了。

具体的检查方式：

• 直接在浏览器地址栏请求一个只存在于前端路由的路径（例如https://你的子域名.puter.site/dashboard），应返回index.html的内容且状态码为200，前端路由接管后正常渲染页面；
• 确认该请求在配置前是 Puter 默认 404、配置后是index.html+200，这个“行为确实变了”的对比才是判定标准；
• 顺手请求/.puter_site_config应得到 404，可用来确认配置文件本身不会暴露给访客。

已知边界与不支持项

• file指向的页面不存在时：访客会拿到 Puter 默认 404，文档确认不存在重定向循环；
• 路径不能逃逸站点：file在你的站点根目录内解析，..段会被剥掉，配置无法指向你没发布的东西；
• 不支持的能力：.puter_site_config不做重定向、URL 重写、自定义响应头、clean URLs、cache-control 规则或目录列表。如果你正从_redirects或vercel.json迁移过来，只有错误页面这一部分有对应能力；
• 有两个改写始终发生、无需配置：请求/或任何目录路径时，直接返回该目录的index.html。

如果你的 SPA 只需要/index.html兜底，以上机制已经足够；需要重定向或改写的逻辑要放到前端路由层解决。

下一步

发布流程的细节（puter.com 操作、CLI 参数、GitHub Actions workflow 完整配置）见 Deployments；需要以编程方式创建和管理站点（例如网站构建器、静态站点生成器）时，使用 Hosting API。字段与行为变更以 Site Configuration 为准。

【免费下载链接】puter🌐 The Internet Computer! Free, Open-Source, and Self-Hostable.项目地址: https://gitcode.com/GitHub_Trending/pu/puter