docs(ssg): add 404.html to output structure and troubleshooting for page refresh 404 (#2987)

SoonIter · Copilot · web-flow · commit 968b67172df4 · 2026-01-09T18:03:13.000+08:00
Co-authored-by: Copilot &lt;175728472+Copilot@users.noreply.github.com&gt;
diff --git a/website/docs/en/guide/basic/deploy.mdx b/website/docs/en/guide/basic/deploy.mdx
@@ -204,3 +204,9 @@ First of all, you need to [create a Zeabur account](https://zeabur.com). Then, f
 Click on `Deploy New Service` and import your Rspress repository, the deployment will be started automatically and Zeabur will recognize that your site is built with Rspress.
 
 The deployment will be finished in a minute, you can also bind a free sub domain provided by Zeabur or your own domain for this site.
+
+## Troubleshooting
+
+### Page shows 404 after refresh
+
+If your site navigates normally but shows a 404 error after refreshing the page, please refer to the ["Page shows 404 after refresh"](/guide/basic/ssg#refresh-404) section in the SSG documentation.
diff --git a/website/docs/en/guide/basic/ssg.mdx b/website/docs/en/guide/basic/ssg.mdx
@@ -72,12 +72,15 @@ doc_build/
 │   └── css/
 │       └── main.[hash].css
 ├── index.html
+├── 404.html
 ├── guide/
 │   └── getting-started.html
 └── api/
     └── config.html
 ```
 
+The `404.html` is automatically generated by Rspress to handle non-existent routes. This file plays an important role in SPA deployment, see ["Page shows 404 after refresh"](#page-shows-404-after-refresh) for details.
+
 ### HTML content differences
 
 The core difference between the two modes lies in the HTML file content:
@@ -207,6 +210,20 @@ function MyComponent() {
 }
 ```
 
+### Page shows 404 after refresh \{#refresh-404}
+
+**Symptom**: Navigating to other pages within the site works normally, but refreshing the page results in a 404 error.
+
+**Cause**: When you refresh the page or directly visit a URL, the request is sent to the server, but the server may not have a corresponding file for that path (especially on some static hosting services).
+
+**Solution**: Most static hosting services (such as GitHub Pages, Netlify, Vercel, etc.) use `404.html` by default to handle all unmatched routes, requiring no additional configuration. If your server doesn't handle this automatically, you need to manually configure it to redirect unmatched requests to `404.html`. The `404.html` generated by Rspress contains the complete application code, which can correctly handle routing on the client side and display the corresponding page.
+
+Here is an example of a `_redirects` file configuring 404.html redirect, which you can use if your hosting service supports it:
+
+```txt title="docs/public/_redirects"
+/*    /404.html   200
+```
+
 ## Configuration
 
 You can control whether SSG is enabled through the `ssg` configuration:
diff --git a/website/docs/zh/guide/basic/deploy.mdx b/website/docs/zh/guide/basic/deploy.mdx
@@ -204,3 +204,9 @@ jobs:
 点击 `Deploy New Service` 并导入你的仓库，部署将会自动开始进行，并且 Zeabur 会自动识别你的站点是使用 Rspress 构建的。
 
 部署将在几分钟内完成，你也可以同时在该页面为你的站点绑定 Zeabur 提供的免费子域名或者自己购买的自定义域名。
+
+## 常见问题
+
+### 刷新页面时出现 404
+
+如果你的站点在导航时正常，但刷新页面后出现 404 错误，请参考 [SSG 文档中的「刷新页面时出现 404」](/guide/basic/ssg#refresh-404) 章节。
diff --git a/website/docs/zh/guide/basic/ssg.mdx b/website/docs/zh/guide/basic/ssg.mdx
@@ -72,12 +72,15 @@ doc_build/
 │   └── css/
 │       └── main.[hash].css
 ├── index.html
+├── 404.html
 ├── guide/
 │   └── getting-started.html
 └── api/
     └── config.html
 ```
 
+其中 `404.html` 是 Rspress 自动生成的 404 页面，用于处理不存在的路由。该文件在 SPA 部署时有重要作用，详见[「刷新页面时出现 404」](#刷新页面时出现-404)。
+
 ### HTML 内容差异
 
 两种模式的核心区别在于 HTML 文件的内容：
@@ -207,6 +210,20 @@ function MyComponent() {
 }
 ```
 
+### 刷新页面时出现 404 \{#refresh-404}
+
+**现象**：在站点内通过链接导航到其他页面正常，但刷新页面后出现 404 错误。
+
+**原因**：当你刷新页面或直接访问某个 URL 时，请求会发送到服务器，但服务器上可能并没有对应路径的文件（尤其是在某些静态托管服务中）。
+
+**解决方案**：大部分静态托管服务（如 GitHub Pages、Netlify、Vercel 等）默认会使用 `404.html` 来处理所有未匹配的路由，无需额外配置。如果你的服务器没有自动处理，需要手动配置将未匹配的请求重定向到 `404.html`。Rspress 生成的 `404.html` 包含完整的应用代码，能够在客户端正确处理路由并显示对应页面。
+
+如果你的托管服务支持 `_redirects` 文件，可以使用以下配置示例：
+
+```txt title="docs/public/_redirects"
+/*    /404.html   200
+```
+
 ## 配置选项
 
 你可以通过 `ssg` 配置来控制是否启用 SSG：
