online 404 error troubleshooting

This page was translated by AI and proofread by humans. You may want to view in original language.

Locally working, online abnormalities

The new added album-type pages support multi-level structures.

While everything works fine locally, some pages display 404 error after deployment to Vercel.

It turns out that 404 pages are all album leaf nodes, meaning these albums have no child albums and display a number of photos.
The directory structure of albums in the public directory is as follows:

albums/
├── animal
│   ├── cat
│   │   └── 1.jpg
│   ├── cat.html
│   ├── dog
│   │   └── 1.jpg
│   ├── dog.html
│   └── index.html
└── index.html

Albums and animal are branch nodes of the album tree and can be accessed without adding index.html. Dog and cat are leaf nodes of the album tree and must be accessed with .html.
For example, the legal access paths for animal are /albums/animal and /albums/animal/index.html.
The only legal access path for dog is /albums/animal/dog.html.

As can be seen in the screenshot above, accessing /albums/animal/dog works fine locally, but results in a 404 error online. The online behavior is actually normal, as dog doesn't have an index.html. So why does local development display normally in an unusual manner?

Abnormal Local Development Behavior

Local development uses Hexo Server, which enables file monitoring and regenerates static pages when files change. While its implementation details aren't particularly explored, I suspect it also performs other file location functions, resulting in the previously unavailable /albums/animal/dog being correctly located at /albums/animal/dog.html .

To verify this hypothesis, you can use http-server.

Installing http-server

pnpm i http-server -g

Starting the Local Server

In the blog root directory, run http-server ./public. If a public page isn't generated, generate it first using hexo g.

Visiting /albums/animal/dog redirects to /albums/animal/dog/

While /albums/animal/dog/ should return index.html, but because dog doesn't have an index.html, the http server returns the page content we see, similar to ls /albums/animal/dog/

Thus, the above speculation (helps with file location) is correct. Hexo Server offers features beyond those similar to Webpack HMR. Here's ChatGPT's answer:

While Hexo Server can also preview locally, it automatically compiles and supports Hexo's dynamic routing, which can sometimes lead to inconsistent behavior with a live static server (e.g., 404 errors, directory redirects). http-server only outputs static files as is, just like uploading a public page to a live server, which makes it ideal for debugging the actual performance of static sites.

Solution

Modifying the Path

To redirect from a branch album to a leaf album, simply add .html to the end of the leaf album's path.

This method can solve some issues, but it doesn't address 404 errors caused by user-modified URLs. Therefore, the following method must be used in conjunction with it.

Adding a New 404 Page

Creating 404.md

Execute hexo new page 404

Modifying Content

Open source/404.md and set the following content:

---
title: 'Page does not exist!'
date: 2025-07-27 16:53:29
type: "404"
comments: false
---

Sorry, the page you requested does not exist or has been deleted.

You will be returned to the homepage in <span id="timeout" style="font-weight: 700;" >5</span> seconds. [Click here](/) to return to the homepage immediately.


<script>
let countTime = 5;

function count() {
  document.getElementById('timeout').textContent = countTime;
  countTime -= 1;
  if(countTime === 0){
    location.href = '/';
  }
  setTimeout(() => {
    count();
  }, 1000);
}

count();
</script>

Modify layout/post.ejs

Open themes/oranges/layout/post.ejs and add the following content above <% if (!page.type) { %>.

<!-- 404 Page -->
<% if (page.type === "404") { %>
 <div class="container post-details album-index">
  <div class="markdown-body">
      <%- page.content %>
  </div>
 </div>
<% } %>

See the results

Visit http://localhost:4000/404

PS: When using Hexo Server as a local server, modifying the URL to access a non-existent path (e.g., /a/b/c/d) will not result in a 404 page. However, using http-server will result in a 404 page for any non-existent path. Therefore, it is recommended to test using http-server before going live.