如何用 .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 CLInpm 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浏览器拿到的是成功响应前端路由才会接管页面。字段参考以文档为准字段类型必填说明errorsobject是把 HTTP 状态码映射到对应的回退页面是唯一的顶层键errors.codeobject—要处理的状态码作为字符串键必须在400–599之间目前只有404真正生效errors.code.filestring是要返回的页面路径以/开头相对于站点根目录errors.code.statusnumber否响应返回的状态码200–599默认与处理的码相同SPA 回退需设为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 则重新执行一次部署。验证时注意文档给出的两个特性改动最多要等一分钟。站点配置有 60 秒缓存刚上传完就测出“没生效”之前先等一分钟再下结论。配置写错是被静默忽略而不是报错。JSON 语法错误、文件超过 64 KB、或结构不符合上面的形状Puter 都会当作文件不存在来处理——站点不会挂但你的改动也悄无声息地不生效。所以文档的要求是检查行为是否真的变了而不是假设它变了。具体的检查方式直接在浏览器地址栏请求一个只存在于前端路由的路径例如https://你的子域名.puter.site/dashboard应返回index.html的内容且状态码为200前端路由接管后正常渲染页面确认该请求在配置前是 Puter 默认 404、配置后是index.html200这个“行为确实变了”的对比才是判定标准顺手请求/.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 如何用 .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 CLInpm 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浏览器拿到的是成功响应前端路由才会接管页面。字段参考以文档为准字段类型必填说明errorsobject是把 HTTP 状态码映射到对应的回退页面是唯一的顶层键errors.codeobject—要处理的状态码作为字符串键必须在400–599之间目前只有404真正生效errors.code.filestring是要返回的页面路径以/开头相对于站点根目录errors.code.statusnumber否响应返回的状态码200–599默认与处理的码相同SPA 回退需设为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 则重新执行一次部署。验证时注意文档给出的两个特性改动最多要等一分钟。站点配置有 60 秒缓存刚上传完就测出“没生效”之前先等一分钟再下结论。配置写错是被静默忽略而不是报错。JSON 语法错误、文件超过 64 KB、或结构不符合上面的形状Puter 都会当作文件不存在来处理——站点不会挂但你的改动也悄无声息地不生效。所以文档的要求是检查行为是否真的变了而不是假设它变了。具体的检查方式直接在浏览器地址栏请求一个只存在于前端路由的路径例如https://你的子域名.puter.site/dashboard应返回index.html的内容且状态码为200前端路由接管后正常渲染页面确认该请求在配置前是 Puter 默认 404、配置后是index.html200这个“行为确实变了”的对比才是判定标准顺手请求/.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考