常见问题

时光2025/10/220 0 m

Vercel 平台子页面单独 URL 访问显示 404

问题现象

在 Vercel 平台部署 VitePress 项目后，通过单独 URL 直接访问子页面时，地址栏会提示 **404 ** ，但在 GitHub Pages 或 EdgeOne平台部署时无此问题。

问题原因

该问题的核心在于 cleanUrl（隐藏文件后缀名）功能的平台配置差异：

• 在 VitePress 中，若你主动启用了 cleanUrl 配置（目的是让 URL 去除 .html 后缀，如 your-domain/docs 而非 your-domain/docs.html），项目会默认按“无后缀 URL”的逻辑生成页面结构。
• 不同平台对 cleanUrl 的默认支持不同：
  • GitHub Pages / Netlify：默认开启 cleanUrl 功能，可正常识别无后缀 URL，因此不会出现 404 错误。
  • Vercel：默认未开启 cleanUrl 功能，无法识别 VitePress 生成的无后缀 URL，导致直接访问子页面时触发 404 错误。

解决方案

只需在项目根目录创建 vercel.json 配置文件，并手动开启 Vercel 的 cleanUrl 功能，即可与 VitePress 的配置保持一致，解决 404 问题。

操作步骤

1. 进入你的 VitePress 项目根目录（与 docs 文件夹、package.json 同级）。
2. 新建一个名为 vercel.json 的文件。
3. 在文件中添加以下配置代码：

vercel.json

{
  "cleanUrls": true
}

4. 将修改后的 vercel.json 文件提交至代码仓库，重新触发 Vercel 部署即可。