Docusaurus wiki页面渲染异常：刷新后右侧面板错位问题求助

针对刷新页面时右侧面板跑到左侧导航下方的问题，整理了几个实用的排查和解决方向：

1. 强制触发布局重绘 #

这个问题大概率是页面刷新时，Docusaurus的布局JS没有及时计算DOM尺寸导致的。可以在页面加载完成后手动触发resize事件，强制重新计算布局：

在项目的src/js/custom.js里添加全局监听：

window.addEventListener('load', () => {
  // 触发resize事件让布局重新计算
  document.dispatchEvent(new Event('resize'));
});

如果用自定义布局组件，也可以通过React的useEffect实现：

// src/components/CustomLayout.js
import React, { useEffect } from 'react';
import Layout from '@theme/Layout';

export default function CustomLayout(props) {
  useEffect(() => {
    // 延迟100ms确保DOM完全加载
    const timer = setTimeout(() => {
      window.dispatchEvent(new Event('resize'));
    }, 100);

    return () => clearTimeout(timer);
  }, []);

  return <Layout {...props} />;
}

记得在docusaurus.config.js里配置使用这个自定义布局。

2. 排查自定义CSS冲突 #

检查你添加的自定义样式，尤其是修改了.docMainContainer、.sidebar、.container这些核心布局类的代码：

• 不要把原生的display: flex改成block或者其他会破坏横向布局的值
• 避免给侧边栏或主内容容器设置width: 100%，这会挤压另一栏的空间
• 移除可能存在的float属性，flex布局下不需要这个

比如原生主容器的样式是：

.docMainContainer {
  display: flex;
  flex: 1 1 auto;
}

如果你的自定义CSS覆盖了这个，就会导致右侧面板换行。

3. 验证侧边栏路由配置 #

检查sidebars.js，确保每个文档页面都正确关联了侧边栏配置。如果刷新时侧边栏组件因为找不到对应配置而重新渲染，也可能导致布局错位。

另外，如果你用了自定义路由逻辑，要确保路由切换后页面的布局状态被正确初始化，没有残留的旧状态影响渲染。

4. 升级Docusaurus版本 #

部分旧版本的Docusaurus存在布局计算的已知bug，升级到最新稳定版可以直接解决这类问题：

npm update @docusaurus/core @docusaurus/preset-classic

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