如何在Docusaurus站点子目录正确集成独立静态站点？

资源加载失败、页面渲染异常本质是两个问题凑一块了：

• Doxygen默认生成的静态资源用的是根路径绝对引用，放到/code子目录后，浏览器会跑到站点根目录而非/code目录下找JS、logo这些资源，直接报404
• Docusaurus是单页应用（SPA），默认会接管所有前端路由，直接访问/code时会优先加载Docusaurus自身的入口文件，不会返回static目录下放的Doxygen首页

直接改Doxygen的生成配置适配子目录，是最省事的方案，从根上解决路径问题：

• 打开Doxygen项目的配置文件Doxyfile
• 找到LINK_AS_ABSOLUTE_URL配置项，把值改成NO，关掉绝对路径引用。改完之后生成的所有页面、资源都会自动用相对路径，不管你把整个Doxygen站点放到哪个子目录，只要内部文件结构不打乱，资源都能正常加载
• 检查PROJECT_LOGO、自定义JS/CSS这类自定义资源的路径，全部填相对于Doxyfile的相对路径，别写站点根绝对路径
• 重新跑Doxygen生成命令，把生成的html目录里的所有文件，直接复制到Docusaurus项目的static/code/目录下，注意别多套一层html文件夹，要保证static/code/index.html就是Doxygen站点的首页

避免SPA路由把Doxygen的路径给接管了：

• 打开docusaurus.config.js，加下面这些配置：

module.exports = {
  // 其他原有配置保持不动
  trailingSlash: true, // 强制带尾斜杠访问目录，避免静态服务路由匹配出错
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        // 原有的docs、blog、theme配置保持不动
        sitemap: {
          exclude: ['/code/**'], // 别把Doxygen页面收录到Docusaurus的站点地图里
        },
      },
    ],
  ],
}

• 本地开发测试的时候，记得带尾斜杠访问http://localhost:3000/code/，webpack dev server不会自动把不带尾斜杠的/code路径映射到目录下的index.html，生产构建完就没这个问题了

如果不方便改Doxygen配置重新生成，直接在静态托管层加路由优先级规则，保证/code路径下的请求不被Docusaurus的SPA规则拦截：

• 所有/code/**路径的请求，优先匹配对应路径的静态文件，找不到的时候返回/code/index.html，别重写到站点根目录的index.html
• Nginx配置参考：

# 注意这个规则要放在Docusaurus根路由规则前面，保证优先级更高
location /code/ {
  try_files $uri $uri/ /code/index.html;
}
location / {
  try_files $uri $uri/ /index.html;
}

• 要是用Vercel、Netlify这类无服务器托管平台，在平台对应的路由配置文件里加相同逻辑的重写规则就行

• 跑npm run build构建Docusaurus生产包
• 跑npm run serve本地预览构建出来的产物
• 访问带尾斜杠的/code/路径，打开浏览器控制台确认没有404报错，测下Doxygen站内导航、搜索、样式渲染都正常就完事了

内容的提问来源于stack exchange，提问作者Maxime Charrière