Docusaurus部署至Vercel时baseUrl配置异常问题求助

核心问题 #

你的问题本质是baseUrl配置与Vercel部署路径的层级冲突：

• 当baseUrl设为/en/时，Docusaurus会给所有资源路径加上/en/前缀，但Vercel默认将build目录作为站点根，资源实际在build下而非build/en，导致加载失败；
• 若将Vercel输出目录改为build/en，Docusaurus又会在该基础上追加/en/前缀，形成build/en/en/的错误路径。

具体解决步骤 #

1. 修正baseUrl配置 #

如果你的站点部署在Vercel根域名下（如测试链接），直接将baseUrl设为根路径/，不要手动添加语言前缀——Docusaurus的多语言机制会自动处理语言路径：

const config = {
  // ...其他配置
  url: process.env.URL,
  baseUrl: '/', // 替换原process.env.BASE_PATH或/en/
  trailingSlash: false,
  // ...
};

若需通过环境变量控制不同部署环境，确保Vercel中BASE_PATH环境变量在根站点部署时设为/。

2. 配置Vercel构建输出目录 #

保持Docusaurus构建命令为npm run build（默认生成到build目录），在Vercel项目设置中：

• 找到Build & Development Settings
• 将Output Directory设为build，不要设为build/en

这样Vercel会把build目录下的所有内容作为站点根，Docusaurus生成的多语言目录（如build/en）会自动映射到访问路径/en/，资源路径也会正确匹配。

3. 检查多语言配置（若为多语言站点） #

确保Docusaurus的i18n配置正确，让框架自动管理语言路径：

i18n: {
  defaultLocale: 'en',
  locales: ['en', 'zh-CN'], // 根据你的需求调整语言列表
  path: 'i18n',
  localeConfigs: {
    en: {
      label: 'English',
      path: 'en',
    },
    'zh-CN': {
      label: '中文',
      path: 'zh-CN',
    },
  },
},

构建后build目录下会生成对应语言的子目录，Vercel部署后访问/en/即可加载对应内容，不会出现路径重复问题。

4. 同步trailingSlash配置 #

确保Vercel的Trailing Slash设置与Docusaurus的trailingSlash: false一致：

• 在Vercel项目设置的Deployment Protection中找到Trailing Slash选项
• 设置为Do not add trailing slashes

总结 #

问题根源是手动在baseUrl中添加语言前缀，与Docusaurus多语言生成的目录结构冲突。让框架自动处理语言路径，保持baseUrl为根路径，同时正确配置Vercel输出目录，即可解决资源加载错误和路径重复问题。

内容的提问来源于stack exchange，提问作者shahriarpshuvo