Taro H5 页面空白？一个 basename 配置引发的「静默 404」

现象：页面空白，但没有任何报错

我们在实际项目中遇到了一个非常隐蔽的问题——Taro 小程序编译为 H5 后，页面完全空白。打开浏览器控制台，没有任何 JS 报错，React DevTools 里 App 组件也正常挂载了。

进一步检查发现：

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

App 能渲染，但所有页面组件都没有加载。这意味着问题不在 React 渲染层，而在路由匹配环节。

定位过程

排查了大半天，依次排除了以下方向：

1. Webpack 打包问题——检查了 chunk 加载，资源都正常返回
2. 页面组件导出问题——小程序端正常运行，排除代码本身的问题
3. React 版本兼容性——降级测试无效

最终锁定在 Taro 的 H5 路由配置上。

根因：basename: '/' 导致路径双斜杠

项目的 config/index.ts 里有这样一段配置：

h5: {
  router: {
    mode: 'browser',
    basename: '/',  // ❌ 问题出在这里
  },
}

看起来完全合理对吧？但 Taro 内部将 basename 传给了 UniversalRouter 的 baseUrl 参数。当 baseUrl 为 '/' 时，路由匹配的路径会变成 //pages/index/index（注意双斜杠），而浏览器实际的 URL 是 /pages/index/index——两者不匹配，所有页面静默返回 404，不抛出任何错误。

修复：一个字符的差别

h5: {
  router: {
    mode: 'browser',
    basename: '',  // ✅ 改成空字符串即可
  },
}

把 '/' 改成 ''，页面立刻恢复正常。

避坑清单

基于这次排查经验，总结几条建议供参考：

1. router.basename 应使用空字符串，而不是 '/'。虽然在大多数路由库中 '/' 是合法值，但 Taro 的 UniversalRouter 处理逻辑不同。

2. H5 开发阶段优先使用 hash 模式。先确认页面能渲染，再切换到 browser 模式处理路径问题，这样可以有效缩小排查范围。

3. 页面空白但无报错，优先查路由。在控制台执行 document.querySelectorAll('.taro_page').length，如果返回 0，基本可以确定是路由匹配失败。

4. 小程序端正常 ≠ H5 端正常。Taro 的跨端编译意味着两端的运行时逻辑有差异，尤其是路由系统，小程序端使用原生导航栈，H5 端使用 UniversalRouter，配置项的含义可能不同。

适用版本

• Taro 4.x（已验证 4.1.11）
• React 18.x
• UniversalRouter 9.x

这类「静默失败」的 bug 往往最耗时间。希望这篇记录能帮大家少走弯路。