【Docusaurus】子路径配置后，build 报错 Error: Unable to build website for locale en

当你把 baseUrl 从 / 改成 /docs/ 之后（官方文档就只提及这一点），本地访问没有问题。但是，构建时 npm run build 报一堆错误，无法部署。

原因是，好多地方的链接需要手工修改！具体如下：

This error is a classic Docusaurus baseUrl gotcha!

When you change baseUrl from / (the default) to /docs/, you are telling Docusaurus that your entire site will be served from https://airoom.chat/docs/.

Docusaurus’s default docs plugin creates routes like /docs/intro for your docs/intro.md file when the baseUrl is /.

However, when you set baseUrl: '/docs/', the root of your Docusaurus application effectively shifts to https://airoom.chat/docs/.
The docs plugin is still configured to generate documentation pages under a routeBasePath (which defaults to /docs).

Here’s the breakdown of what’s happening:

1. Original (default) setup:

   • url: 'https://airoom.chat'
   • baseUrl: '/'
   • docs/intro.md generates a page at https://airoom.chat/docs/intro.
   • Links in your docusaurus.config.js (navbar, footer) to /docs/intro work correctly.

2. New setup:

   • url: 'https://airoom.chat'
   • baseUrl: '/docs/'
   • Now, Docusaurus assumes its entire site content (including the docs) will live under https://airoom.chat/docs/.
   • The docs plugin still wants to generate pages with a /docs prefix relative to the Docusaurus site root.
   • So, docs/intro.md now generates a page at https://airoom.chat/docs/docs/intro. (Notice the double /docs/docs/ segment).
   • The Problem: Your docusaurus.config.js (and potentially some markdown links) still contain hardcoded links like to: '/docs/intro'. Docusaurus now interprets this as “link to /docs/intro relative to my current baseUrl.”
   • So, a link to: '/docs/intro' becomes https://airoom.chat/docs/docs/intro.
   • But the error message clearly states “linking to /docs/intro” is broken. This means the links are trying to point to https://airoom.chat/docs/intro, which Docusaurus cannot find because the actual page is now at https://airoom.chat/docs/docs/intro.

The Fix:

You need to adjust the hardcoded links in your docusaurus.config.js (and any other places like Markdown files if they use absolute paths) to reflect the new effective URL structure.

Specifically, if baseUrl is /docs/, and your docs plugin has routeBasePath: '/docs/' (the default for the docs plugin), then your links should be relative to the site root, and the docs prefix will be handled by the plugin itself.

Here’s how to fix it:

1. Open docusaurus.config.js.

2. Locate navbar items and footer links.
   Look for entries like these:

   // In navbar.items:
   {to: '/docs/intro', // <--- This is the problem!label: 'Tutorial',position: 'left',
   },
   // In footer.links:
   {title: 'Docs',items: [{label: 'Tutorial',to: '/docs/intro', // <--- This is also the problem!},],
   },
   

3. Change the to paths:
   Instead of '/docs/intro', you should use '/intro'. Docusaurus will then correctly resolve it relative to the baseUrl and the docs plugin’s routeBasePath.

   Correction for default docs plugin behavior:
   If your docs plugin is configured like this (which is the default):

   plugins: [['@docusaurus/plugin-content-docs',{id: 'default', // The default instance of the docs pluginpath: 'docs',routeBasePath: '/docs', // This means docs are available at /docs/ relative to the site's baseUrlsidebarPath: require.resolve('./sidebars.js'),// ... other options},],
   ],
   

   And your baseUrl is /docs/. Then the intro page (from docs/intro.md) will be available at https://airoom.chat/docs/docs/intro.

   The error “linking to /docs/intro” implies that the configuration is expecting https://airoom.chat/docs/intro.

   The most common fix is to change the routeBasePath of the docs plugin if you want your docs to live directly under the baseUrl.

   Option 1 (Recommended if you want https://airoom.chat/docs/intro):
   Modify the plugin-content-docs configuration in docusaurus.config.js. You need to tell the docs plugin that its base path is _relative to the site's baseUrl_. If you set baseUrl: '/docs/', then you want the intro page to be at /intro relative to /docs/.

   In docusaurus.config.js, find the plugins array. For the @docusaurus/plugin-content-docs entry, change routeBasePath to /:

   // docusaurus.config.js
   module.exports = {url: 'https://airoom.chat',baseUrl: '/docs/', // Your site is served from /docs/// ...plugins: [['@docusaurus/plugin-content-docs',{id: 'default',path: 'docs', // Your markdown files are in the 'docs' folderrouteBasePath: '/', // <--- CHANGE THIS! This means your docs will be directly under baseUrlsidebarPath: require.resolve('./sidebars.js'),// ... other options},],],// ...navbar: {// ...items: [{type: 'docSidebar', // Or if using 'to' directly:sidebarId: 'tutorialSidebar',position: 'left',label: 'Tutorial',},{to: '/intro', // <--- If you have explicit links, change them to '/intro' (relative to baseUrl)label: 'Intro Doc',position: 'left',},// ...],},footer: {// ...links: [{title: 'Docs',items: [{label: 'Tutorial',to: '/intro', // <--- Change this too!},],},],},// ...
   };
   

   Explanation for Option 1:

   • baseUrl: '/docs/': Your entire Docusaurus application lives at https://airoom.chat/docs/.
   • routeBasePath: '/' for the docs plugin: The docs plugin will serve its content directly from the root of the Docusaurus application.
   • So, docs/intro.md will become https://airoom.chat/docs/intro.
   • Links like { to: '/intro' } will correctly point to https://airoom.chat/docs/intro.

   Option 2 (If you really want https://airoom.chat/docs/docs/intro):
   This means you want the docs prefix to appear twice in the URL. In this case, your routeBasePath should remain /docs, and your links in docusaurus.config.js should point to the double-prefixed path.

   // docusaurus.config.js
   module.exports = {url: 'https://airoom.chat',baseUrl: '/docs/',// ...// Assuming routeBasePath for docs plugin remains '/docs' (default)// ...navbar: {// ...items: [{to: '/docs/intro', // <--- This link is now correct IF routeBasePath is also '/docs'label: 'Intro Doc',position: 'left',},// ...],},footer: {// ...links: [{label: 'Tutorial',to: '/docs/intro', // <--- This link is now correct IF routeBasePath is also '/docs'},],},// ...
   };
   

   The error “linking to /docs/intro” being broken suggests that Docusaurus is not finding https://airoom.chat/docs/docs/intro when it processes your links. This is less common and usually indicates an additional misconfiguration or expectation mismatch.

Given your error message, Option 1 is the most likely solution. The error “linking to /docs/intro” means that your navbar/footer links are trying to point to baseUrl + /docs/intro, which is https://airoom.chat/docs/docs/intro, but Docusaurus can’t find it. If you use Option 1, the links become baseUrl + /intro, which is https://airoom.chat/docs/intro, and that’s usually where docs/intro.md would live under the adjusted routeBasePath.

In summary, the most robust and common approach when baseUrl is /docs/ is:

1. Set baseUrl: '/docs/' in docusaurus.config.js.
2. Set routeBasePath: '/' for your default docs plugin instance in docusaurus.config.js.
3. Update any explicit links in navbar.items or footer.links from to: '/docs/intro' to to: '/intro'.

After making these changes, clear your Docusaurus cache (rm -rf .docusaurus build) and try building again: npm run build or yarn build.