Routing access failure after server Nginx deployment

[Charles7c]

Describe the bug

Recently, I deployed a document site on my server through Nginx and found that if I directly access the specified route, it will be forwarded to the homepage, but the routing address is the one that was accessed. At this point, clicking on other navigation options on the page would be confusing. And I have deployed a site on GitHub without experiencing this issue. I suspect it is a Nginx configuration issue. Can you help me take a look at the problem?

Reproduction

1.pnpm build
2.upload the content from dist to Nginx server
3.accessing Sites

Expected behavior

Expect normal routing access.

System Info

System:
    OS: Windows 10 10.0.19045
    CPU: (24) x64 13th Gen Intel(R) Core(TM) i7-13700K
    Memory: 21.30 GB / 31.75 GB
  Binaries:
    Node: 18.16.0 - D:\Develop\nodejs\node.EXE
    npm: 9.5.1 - D:\Develop\nodejs\npm.CMD
    pnpm: 8.6.12 - ~\AppData\Roaming\npm\pnpm.CMD
  Browsers:
    Edge: Spartan (44.19041.1266.0), Chromium (115.0.1901.203)
    Internet Explorer: 11.0.19041.1566

Additional context

N/A

Validations

• Check if you're on the latest VitePress version.
• Follow our Code of Conduct
• Read the docs.
• Check that there isn't already an issue that reports the same bug to avoid creating a duplicate.

[kiaking]

Please use Discord or GitHub Discussions for a question 👍

And when you do, don't forget to paste your Nginx config so that people can see what's wrong with it 👀

[Charles7c]

I have preliminarily resolved this issue by configuring cleanUrls to true in vitepress, the article directory structure of my project does not meet the corresponding requirements. Now I have removed this configuration, which means changing from /foo to /foo.html.

[Charles7c]

Do you have any other good solutions or configurations? Welcome to share them?

[brc-dd]

I haven't used nginx much. Someone from the community might have insights. If there is a good enough configuration, we can add it to the deploy docs too.

[Lazydd]

nginx加这个，匹配的路径/docs/改成你的
location /docs/ { index index.html index.htm; try_files $uri $uri.html $uri/ /index.html; }

[Charles7c]

Yes, I have tested both with cleanUrls set to true and without it, and the configuration resolves my issue. If the resource indeed does not exist, it will redirect to the homepage. In theory, this configuration is not problematic. In the provided try_files directive, the resource lookup order is specified, and if it cannot be found, it returns the content of /index.html. Therefore, a special treatment may be needed for 404 situations.

[Charles7c]

I temporarily disabled the configuration of cleanUrls for now. :)

[qweasdzxcpkh]

hi, i just add an other trick method to resolve this, in my case i have custom component at home page:

that component has multi link writen by <a>, it also have these problem, but when i add target="self" attribute for the link, it solve, because of this:
https://stackoverflow.com/a/28802951/24381611
again, it is a trick method. if you can control your nginx config, don't use this

btw, i am curious about docs:preview command have this issue with [email protected], is it any work going on with this? @brc-dd

[brc-dd]

docs:preview doesn't have any issue. Please create a separate issue if docs:preview is not working. Regarding nginx, it's fucked up and none of the configurations here perfectly work.

[qweasdzxcpkh]

docs:preview doesn't have any issue. Please create a separate issue if docs:preview is not working. Regarding nginx, it's fucked up and none of the configurations here perfectly work.

thanks, i finally figure it out was the custom component using element-plus's el-popover component, it requires <client-only>.

[meduzen]

Edit: I published a blog post about this 👇.

Hi! I’m only starting with Vitepress, but here’s how I solved it with Nginx:

1. Enable cleanUrls: true.
2. Use the following Nginx location block:

    location / {

        # defines which custom page to serve for 404 status code
        error_page 404 /404.html;

        # if `foo/bar` nor `foo/bar.html` nor `foo/bar/index.html` can’t work, answer with 404
        try_files $uri $uri.html $uri/ =404;
    }

This has been tested on the following files structure.

Markdown	HTML build	Valid path(s)	Invalid path
/index.md	/index.html	/ and /index.html	-
/notes.md	/notes.html	/notes and /notes.html	/notes/ (403, see next paragraph)
/notes/my-note.md	/notes/my-note.html	/notes/my-note, /notes/my-note/, /notes/my-note.html	-
-	404.html	-	/lol, /lol/, /lol/index.html, /lol/whatever.html

3. To avoid the 403 on paths with a trailing slash (e.g. my-blog.com/ or my-blog.com/notes/), we can redirect them to their non-trailing slash version using the rewrite directive in the server block:

server {
    # many things here…

    # remove trailing slash
    rewrite ^(.+)/+$ $1 permanent;

    location / {

        # defines which custom page to serve for 404 status code
        error_page 404 /404.html;

        # if `foo/bar` nor `foo/bar.html` nor `foor/bar/index.html` can’t work, answer with 404
        try_files $uri $uri.html $uri/ =404;
    }
}

Note that the permanent keyword do a 301 redirect, which is permanent and might be cached during a very long time by your browser (and also a while longer by search engines). If for some reason you want it to be temporary (302), use the redirect keyword.

Well, I think this is gonna be my first article on my blog using Vitepress. 😄 I’ll probably also PR this for the Vitepress deploy guide.

[meduzen]

If you have an example of this, I’m curious. I don’t see any scenario where a trailing slash is applicable to something else than a URL in the context of Vitepress. Maybe something I still have to understand or discover. 🤔

[brc-dd]

Suppose you've something like this in your some page say foo/index.md (and you've image at public/logo.png

---
layout: home

hero:
  name: VitePress
  text: Vite & Vue powered static site generator.
  tagline: Lorem ipsum...
  image:
    src: '../logo.png'
    alt: VitePress
---

here logo.png will break if you remove trailing slash from /foo/. you'll need to reference it as /logo.png or if you've base, then /base/logo.png

[meduzen]

Just tested with the following file structure, and I don’t have the issue you mention.

Using Vitepress config with cleanUrls: true and the Nginx config from my first answer.

As input:

• /public/logo.png
• /notes/my-title.md:

---
layout: home

hero:
  name: Test
  text: Let’s test something.
  tagline: Lorem ipsum...
  image:
    src: '../logo.png'
    alt: VitePress
---

We are in `/notes/my-title.md`, and frontmatter `hero.image.src` is `'../logo.png'`.

Build:

• /logo.png
• /notes/my-title.html

Try it by yourself on these URLs (I’ll unpublish them once the conversation is resolved):

• https://blog.mehdi.cc/notes/my-title
• https://blog.mehdi.cc/notes/my-title/ (which removes the trailing slash and redirects to https://blog.mehdi.cc/notes/my-title)
• https://blog.mehdi.cc/notes/my-title.html

You can see the hero picture is <img class="VPImage image-src" src="../logo.png" alt="VitePress" data-v-8426fc1a="">, which does not impact its loading as trailing URLs are removed.

[brc-dd]

should happen only with xxx/index.md kind of files. and I don't think you'll be able to remove trailing slash from those files (vitepress probably auto adds it even if you have removed it).

[meduzen]

Okay, got it! Indeed, it creates an infinite redirection loop between /path/ and /path. Only /test/index.html is working normally. (I saw you brought many routing feature, I have to look up why Vitepress forces the slash).

So I see 3 paths:

1. Use /path.mdover /path/index.md as it doesn’t break leading slash, which is what I’m doing for now.
2. Don’t remove the trailing slash, but it exposes to a 403.
3. Always add a trailing slash, which at first attempt seems to be more complicated with Nginx.

Thanks for your time, by the way! I still have to experiment with dynamic stuff (e.g. building an index of /notes/*).