Vitepress项目部署Vercel时自动加载404页面的解决方案

在使用Vitepress构建文档网站并部署到Vercel平台时，开发者可能会遇到一个常见问题：网站自动加载404.html页面而非预期的首页内容。这种情况通常是由于项目配置与Vercel部署设置不匹配导致的。

问题现象

当开发者按照标准流程初始化Vitepress项目并部署到Vercel后，访问网站根路径时却显示404页面。检查构建输出目录时，可能会发现缺少index.html文件，只有404.html文件存在。

根本原因分析

这个问题的主要根源在于Vitepress初始化位置与Vercel默认配置之间的不匹配。当使用npx vitepress init ./命令在当前目录(而非docs子目录)初始化项目时，构建输出路径会有所不同，但Vercel的默认配置仍假设项目结构是标准Vitepress布局。

具体来说，标准Vitepress项目结构通常将文档内容放在docs目录下，构建输出到docs/.vitepress/dist目录。而当项目直接初始化在当前目录时，构建输出路径变为.vitepress/dist，这与Vercel的预设配置产生了偏差。

解决方案

要解决这个问题，需要手动调整Vercel的项目配置，使其与实际的Vitepress项目结构保持一致：

1. 在Vercel部署过程中，当提示检测到本地设置时，选择修改配置
2. 明确指定构建命令为npm run docs:build
3. 设置开发命令为npm run docs:dev -- --port $PORT
4. 最关键的是将输出目录调整为.vitepress/dist

配置建议

对于直接在项目根目录初始化Vitepress的情况，建议采用以下配置组合：

• 构建命令：保持为npm run docs:build不变
• 输出目录：必须设置为.vitepress/dist而非默认的docs/.vitepress/dist
• 开发命令：调整为包含端口参数的格式

这种配置调整确保了Vercel能够正确找到Vitepress生成的静态文件，包括index.html首页文件。

最佳实践

为避免此类问题，建议开发者：

1. 统一项目结构，尽量采用Vitepress推荐的标准目录布局
2. 在初始化项目时明确指定目录结构
3. 部署前先在本地测试构建结果，验证输出目录结构
4. 熟悉Vercel配置选项，特别是与构建输出相关的设置

通过正确配置构建路径和输出目录，可以确保Vitepress项目在Vercel平台上正常部署和运行，避免404页面意外出现的问题。