1***@qq.com

发布：2026-08-18 15:52
更新：2026-08-18 15:53
阅读：33

【报Bug】Vue3引入Pinia后在nvue页面使用，H5端报错Hydration completed but contains mismatches.,APP端打开直接白屏

分类：uni-app

bug反馈

产品分类： uniapp/App

PC开发环境操作系统： Windows

PC开发环境操作系统版本号： 21H2

HBuilderX类型：正式

HBuilderX版本号： 5.24

手机系统： Android

手机系统版本号： Android 14

手机厂商：华为

手机机型： Honor V30 Pro

页面类型： nvue

vue版本： vue3

打包方式：云端

项目创建方式： HBuilderX

示例代码：

// 使用的是官方引入方式

import { createSSRApp } from 'vue'
import * as Pinia from 'pinia' // 关键：使用命名空间导入

export function createApp() {
const app = createSSRApp(App)
// 通过 Pinia 命名空间调用 createPinia
app.use(Pinia.createPinia());
return {
app,
// 关键：必须将 Pinia 命名空间对象返回，而非 pinia 实例
Pinia
}
}

操作步骤：

引入Pinia，在nvue页面使用

预期结果：

正常运行

实际结果：

无法正常运行

bug描述：

H5端，在控制台报警告：Hydration node mismatch:
APP端，打开后直接白屏，无法显示

2026-08-18 15:52 负责人:无分享

1 个回复

Ask小助手 - Ask社区AI助手

欢迎到专业群（ uni-app 官方技术交流群 1 ）咨询，群中有相关专业的管理员和群友。

好的，收到你的 Bug 反馈。作为 DCloud 官方人员，我对这个反馈进行如下评审和分析：

1. 反馈质量评审

这个 Bug 反馈整体描述比较清晰，分类信息完整，但代码示例部分不够充分，影响问题定位。

BUG 标题与描述：标题准确概括了问题核心（Vue3 引入 Pinia 后在 nvue 页面使用，H5 报 Hydration mismatch，App 白屏）。描述清晰，官方人员能够看懂。
代码示例：不够完整。你只提供了 main.js（或 main.ts）的引入代码，但缺少了在 nvue 页面中具体如何调用 Pinia 的代码。这对于排查“白屏”和“报错”至关重要，因为很多类似问题实际上是由于在页面外调用 Store 时机过早导致的。
复现步骤：描述为“引入Pinia，在nvue页面使用”，结合代码示例可以理解大致流程，但由于缺少 nvue 页面的代码，官方人员无法直接复现。建议补充 nvue 页面调用 Pinia 的完整代码示例。
预期结果：“正常运行”是合理的预期。
实际结果：H5 端报 Hydration mismatch 警告，App 端白屏，这是不正常的运行状态。
分类信息：非常完整。包含了 PC 环境（Windows 21H2）、HBuilderX 版本（正式版 5.24）、手机 OS（Android 14）、Vue 版本（Vue3）和具体机型（Honor V30 Pro），为排查提供了良好基础。
附件说明：由于系统限制，我无法识别附件内容，如果有关键报错截图，请将日志以文本形式补充在描述中。

评审结论：反馈有效，但请补充 nvue 页面调用 Pinia 的代码示例，以便更准确地定位问题。

2. 问题分析与排查

根据你提供的代码和知识库中的相关信息，这个问题成立的依据比较充分，主要与 Pinia 的引入写法 以及 Store 的调用时机 有关。

引入写法分析：你的 main.js 代码使用的是 import * as Pinia from 'pinia'，并通过 app.use(Pinia.createPinia()) 注册，同时返回了 Pinia 命名空间。这符合 uni-app 官方文档中对于 Vue3 项目引入 Pinia 的说明（参考状态管理 Pinia）。官方文档明确指出，Vue3 项目内置了 Pinia（版本 2.1.7），HBuilderX 无需手动安装。
已知类似问题：在 ask 社区中，有多个关于在 App 端（尤其是 nvue 页面）使用 Pinia 导致白屏的反馈（例如【报Bug】在nvue页面使用pinia报错、【报Bug】vue3+pinia+uniapp在app端白屏）。
根因推断：
1. 调用时机过早：这是最常见的原因。如果在 nvue 页面的 <script> 顶部直接解构并调用 Store（例如 const store = useStore()），在 App 端可能会因为上下文尚未初始化完毕而导致白屏报错（如 createInstanceContext failed）。
2. H5 端 Hydration mismatch：通常是因为服务端渲染和客户端渲染的 DOM 结构不一致导致的。如果在渲染期间直接使用了 Pinia 中的状态，而该状态在初始化时存在异步或延迟，可能会导致节点不匹配。

3. 解决方案与建议

建议你按照以下步骤进行排查和修改：

检查 Store 调用时机：
请确保在 nvue 页面中使用 Pinia 时，不要在 <script setup> 的顶层或组件外部直接调用 Store 获取数据。应该将调用放在生命周期钩子（如 onLoad、onShow）或事件函数内部。

错误示例（可能导致白屏）：
```
import { useCounterStore } from '@/store/counter';  
const store = useCounterStore(); // 不要在顶层直接调用  
```
本助手使用国产模型，生成代码可能不准确。专业的代码生成需要全球顶尖的AI Coding模型。推荐使用uni-agent

正确示例：
```
import { useCounterStore } from '@/store/counter';  
const store = useCounterStore(); // 在 setup 中定义是可以的，但避免在此时执行依赖上下文的操作  

// 如果需要初始化获取数据，放在生命周期里  
onLoad(() => {  
    store.getData();  
});  
```
本助手使用国产模型，生成代码可能不准确。专业的代码生成需要全球顶尖的AI Coding模型。推荐使用uni-agent
对比官方示例：
请参考 uni-app 官方文档中的 Pinia 使用示例，确认你的 main.js 和 Store 定义文件是否与官方推荐写法完全一致。修改后，务必重新运行项目（不要只热更新）。
清理缓存：
如果确认代码无误，尝试在 HBuilderX 中清除缓存并重新编译运行，以排除旧编译缓存导致的问题。

如果上述步骤仍无法解决，请补充你的 nvue 页面代码示例，以便进一步排查。

内容为 AI 生成，仅供参考

要回复问题请先登录或注册

【报Bug】Vue3引入Pinia后在nvue页面使用，H5端报错Hydration completed but contains mismatches.,APP端打开直接白屏

操作步骤：

引入Pinia，在nvue页面使用

预期结果：

正常运行

实际结果：

无法正常运行

bug描述：

1 个回复

1. 反馈质量评审

2. 问题分析与排查

3. 解决方案与建议

公告

相关问题

【报Bug】Vue3引入Pinia后在nvue页面使用，H5端报错Hydration completed but contains mismatches.,APP端打开直接白屏

操作步骤： 引入Pinia，在nvue页面使用

预期结果： 正常运行

实际结果： 无法正常运行

bug描述：

与内容相关的链接

1 个回复

1. 反馈质量评审

2. 问题分析与排查

3. 解决方案与建议

公告

相关问题

操作步骤：

引入Pinia，在nvue页面使用

预期结果：

正常运行

实际结果：

无法正常运行