添加trailingSlash: false后Docusaurus网站出现404错误求助

云上老周

2026-7-31

问题

使用Docusaurus 2.0.0-beta.18搭建网站，生产环境中点击侧边栏项进入https://www.mywebsite.com/docs/a-page，刷新后URL变为https://www.mywebsite.com/docs/a-page/，本地无此问题。希望URL保持一致且不带末尾斜杠，遂在docusaurus.config.js中添加trailingSlash: false，部署后大部分页面返回404，静态资源正常。设置trailingSlash: true时网站可正常访问，URL带末尾斜杠。

相关配置

docusaurus.config.js

const path = require('path');
module.exports = {
  title: 'my website',
  tagline: 'The tagline of my site',
  onBrokenLinks: 'ignore',
  url: 'https://www.mywebsite.com',
  baseUrl: '/', // if we use GitHub Pages, we need to set this to '/docusaurus/', and also change routing links in some pages
  favicon: 'img/favicon.ico',
  organizationName: 'softtimur', // Usually your GitHub org/user name.
  projectName: 'docusaurus', // Usually your repo name.
  trailingSlash: false,
  plugins: [
    path.resolve(__dirname, './plugins/monaco-loader'),
  ],
  themeConfig: {
    navbar: {
      title: 'my website',
      logo: {
        alt: 'My Site Logo',
        src: 'img/logo.svg',
      },
      items: [
        {
          label: 'Documentation', position: 'left',
          items: [
            { label: 'Introduction', to: 'docs/introduction' },
            { label: 'Getting Started', to: 'docs/try-samples' }
          ]
        },
        { to: 'demo', label: 'Live Demo', position: 'left' }, // to src/pages/demo.js
        {
          label: 'Persons', position: 'left',
          items: [
            { label: 'Get my website', to: 'docs/consumer-buy' },
            { label: 'Follow Free Videos and Contents', to: 'docs/free-videos' },
            { label: 'Request a Help', to: 'docs/help-your-work' }
          ]
        },
        {
          label: 'Businesses', position: 'left',
          items: [
            { label: 'Get my website Together', to: 'docs/group-buy' },
            { label: 'Other Services', to: 'docs/web-development' }
          ]
        },
        {
          label: 'Language and Programming', position: 'left',
          items: [
            { label: 'Course in English', to: 'https://go.mywebsite.com/RJ2HPz' },
            { label: 'Course in Chinese', to: 'https://go.mywebsite.com/2KjQzL' },
          ]
        },
        {
          to: '#',
          position: 'right',
        },
        {
          to: '/logout',
          label: 'Sign Out',
          position: 'right',
        },
        {
          to: '/login',
          label: 'Sign In',
          position: 'right',
        },
        {
          type: 'localeDropdown',
          position: 'right',
        },

      ],
    },
    footer: {
      style: 'dark',
      links: [
        {
          title: 'Documentation',
          items: [
            {
              label: 'Try samples',
              to: 'docs/try-samples',
            },
            {
              label: 'Installation',
              to: 'docs/installation',
            }
          ],
        },
        {
          title: 'Philosophy and Research',
          items: [
            {
              label: 'Fundamentals',
              to: 'docs/fundamentals'
            },
          ],
        },
        {
          title: 'Community',
          items: [
            {
              label: 'LinkedIn',
              href: 'https://www.linkedin.com/in/softtimur/'
            }
          ],
        },
        {
          title: 'Company',
          items: [
            {
              label: 'About Us',
              to: 'docs/about-us'
            },
            {
              label: '❤ We are hiring!',
              to: 'docs/hiring'
            }
          ],
        }
      ],
    },
  },
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        googleAnalytics: {
          trackingID: 'UA-68622074-6',
        },
        docs: {
          sidebarPath: require.resolve('./sidebars.js'),
        },
        theme: {
          customCss: require.resolve('./src/css/custom.css'),
        },
        sitemap: {
          changefreq: 'weekly',
          priority: 0.5,
        },
      },
    ],
  ],
  scripts : [
    '/js/patch.js'
  ],
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'zh-CN'],  // Add 'zh-CN' here
    localeConfigs: {
      en: {
        label: 'English',
        htmlLang: 'en-GB',
      },
      'zh-CN': {   // Add this section for Simplified Chinese
        label: '简体中文',
        htmlLang: 'zh-Hans',
      },
    },
  }
};

Nginx配置

gzip on;
gzip_proxied any;
gzip_disable "msie6";
gzip_vary on;
gzip_proxied any;
gzip_comp_level 6;
gzip_buffers 16 8k;
gzip_http_version 1.1;
gzip_min_length 256;
gzip_types text/plain text/css application/json application/javascript application/x-javascript text/xml application/xml application/rss+xml text/javascript application/vnd.ms-fontobject application/x-font-ttf font/opentype image/jpeg image/png image/svg+xml image/x-icon;


server {
  listen  3002;
  absolute_redirect off;
  root  /app;

  location = / {
    rewrite ^(.*)$ https://$http_host/docs/introduction redirect;
  }

  location = /docs {
    rewrite ^(.*)$ https://$http_host/docs/introduction redirect;
  }

  location / {
    try_files $uri $uri/ =404;
  }
}


upstream funfun {
   server 178.62.87.72:443;
}


server {
    listen              443 ssl;
    ssl_certificate     /etc/letsencrypt/live/www.mywebsite.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/www.mywebsite.com/privkey.pem;
    server_name www.mywebsite.com;
    ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
    ssl_prefer_server_ciphers on;
    ssl_session_timeout 1d;
    ssl_stapling on;
    ssl_stapling_verify on;
    add_header Strict-Transport-Security max-age=15768000;
    add_header X-Frame-Options "";

    proxy_ssl_name "www.funfun.io";
    proxy_ssl_server_name on;
   
    location ~ /auth/(.*) {                                                                                            
          proxy_pass  https://funfun/mywebsite/auth/$1?$query_string;
          proxy_set_header Host www.mywebsite.com;
    }

    location / {
        proxy_set_header    Host                $host;
        proxy_set_header    X-Forwarded-For     $proxy_add_x_forwarded_for;
        proxy_set_header    X-Forwarded-Proto   $scheme;
        proxy_set_header    Accept-Encoding     "";
        proxy_set_header    Proxy               "";
        proxy_pass          http://docusaurus:3002/;

        # These three lines added as per https://github.com/socketio/socket.io/issues/1942 to remove socketio error
        proxy_http_version 1.1;
        proxy_set_header   Upgrade $http_upgrade;
        proxy_set_header   Connection "upgrade";
    }
}

server {
    listen 443 ssl;
    server_name mywebsite.com;
    ssl_certificate /etc/letsencrypt/live/mywebsite.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/mywebsite.com/privkey.pem;

    # Additional SSL settings (same as your existing www server block)
    ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
    ssl_prefer_server_ciphers on;
    ssl_session_timeout 1d;
    ssl_stapling on;
    ssl_stapling_verify on;

    return 301 https://www.mywebsite.com$request_uri;
}

server {
    listen 80;
    server_name mywebsite.com;

    return 301 https://www.mywebsite.com$request_uri;
}

原因分析

当设置trailingSlash: false时，Docusaurus的静态文件生成逻辑会改变：原本trailingSlash: true时，每个页面会生成docs/a-page/index.html；设置为false后，会直接生成docs/a-page.html。

但你的Nginx配置中，处理静态文件的location /块使用了try_files $uri $uri/ =404;，这个规则的逻辑是：

先尝试访问请求的路径$uri（比如/docs/a-page）
如果找不到，尝试访问带末尾斜杠的路径$uri/（比如/docs/a-page/）
都找不到就返回404

而实际存在的文件是/docs/a-page.html，Nginx不会自动尝试添加.html后缀，因此匹配不到任何文件，返回404。

解决方案

修改Nginx中监听3002端口的server块里的location /规则，让它尝试匹配.html后缀的文件，有两种可行方式：

方式一：调整try_files规则

把原来的try_files $uri $uri/ =404;改成：

try_files $uri $uri.html $uri/ =404;

这样Nginx会先找$uri，找不到就找$uri.html，再找不到才找$uri/，最后返回404，就能匹配到Docusaurus生成的a-page.html文件。

方式二：使用重写规则

如果不想修改try_files，也可以在location /块内添加重写规则：

rewrite ^([^.]+)$ $1.html permanent;

这样当请求不带后缀的路径时，自动加上.html后缀去查找文件。

修改后重启Nginx容器，设置trailingSlash: false的网站就能正常访问，URL也会保持不带末尾斜杠的格式。

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

添加trailingSlash: false后Docusaurus网站出现404错误求助

问题 #

相关配置 #

docusaurus.config.js

Nginx配置

原因分析 #

解决方案 #

方式一：调整try_files规则 #

方式二：使用重写规则 #

问题

相关配置

原因分析

解决方案

方式一：调整try_files规则

方式二：使用重写规则