Taro H5 Blank Page: A Silent 404 Caused by Router basename

The Problem: Blank Page, Zero Errors

We recently hit a subtle issue in a project — after compiling a Taro mini-program to H5, the page was completely blank. No JavaScript errors in the console. React DevTools showed the App component mounted fine.

A closer look revealed:

• App mounted: true ✅
• Taro pages: 0 ❌
• document.querySelectorAll('.taro_page').length returned 0

The App was rendering, but none of the page components loaded. This pointed to a routing issue rather than a React rendering problem.

The Investigation

We spent the better part of a day ruling things out:

1. Webpack bundling — all chunks loaded correctly
2. Component exports — the mini-program build worked fine, so the code itself was valid
3. React version compatibility — downgrade tests made no difference

Eventually, we narrowed it down to Taro's H5 router configuration.

Root Cause: basename: '/' Creates a Double Slash

The project's config/index.ts contained:

h5: {
  router: {
    mode: 'browser',
    basename: '/',  // ❌ This is the culprit
  },
}

Looks perfectly reasonable, right? But internally, Taro passes basename to UniversalRouter as the baseUrl parameter. When baseUrl is '/', the router tries to match paths like //pages/index/index (note the double slash), while the actual browser URL is /pages/index/index. Nothing matches, and every page silently returns a 404 — with no error thrown.

The Fix: One Character Difference

h5: {
  router: {
    mode: 'browser',
    basename: '',  // ✅ Use an empty string
  },
}

Change '/' to '', and pages render immediately.

Lessons Learned

Based on this debugging experience, here are a few takeaways:

1. Set router.basename to an empty string, not '/'. While '/' is valid in most routing libraries, Taro's UniversalRouter handles it differently.

2. Start H5 development with hash mode. Confirm that pages render first, then switch to browser mode. This helps isolate routing issues from rendering issues.

3. Blank page with no errors? Check routing first. Run document.querySelectorAll('.taro_page').length in the console — if it returns 0, the router isn't matching any pages.

4. Working on mini-program ≠ working on H5. Taro's cross-platform compilation means the two targets have different runtime behaviors, especially in routing. The mini-program uses a native navigation stack, while H5 uses UniversalRouter — config options may behave differently.

Tested Versions

• Taro 4.x (verified on 4.1.11)
• React 18.x
• UniversalRouter 9.x

Silent failures like this are the most time-consuming bugs to track down. Hopefully this write-up saves someone a few hours.