本文详解 Pinia 组合式 API（setup store）中异步动作的正确 await 方式，重点解决因错误解构 ref 导致的响应性丢失、undefined 返回值及 Promise 未正确等待等问题，并提供可直接落地的修复方案与最佳实践。
本文详解 pinia 组合式 api（setup store）中异步动作的正确 await 方式，重点解决因错误解构 `ref` 导致的响应性丢失、`undefined` 返回值及 promise 未正确等待等问题，并提供可直接落地的修复方案与最佳实践。
在使用 Pinia 的组合式 API（即 defineStore 配合 setup() 函数）时，一个常见但极易被忽视的陷阱是：对 store 内部 ref 响应式变量进行对象解构（如 const { widgets } = dashboardStore），会破坏其响应性连接，导致后续读取为 undefined 或无法反映最新状态。这正是你遇到 values is undefined 错误的根本原因——getWidgets() 中解构出的 widgets 已不再是响应式引用，且 loadWidgets() 返回的是 useFetch 的 Promise 包装对象，而非实际数据；而你又试图在 .then() 中访问已失效的 widgets.value。
✅ 正确做法：保持响应式引用 + 显式等待 fetch 完成
首先，修正 store 中 loadWidgets 的实现：useFetch 默认返回一个包含 data、pending、error 等属性的对象，它本身不自动 resolve 数据。你需要显式 await 其内部的 data（或通过 execute() 触发请求并等待完成）。同时，避免解构 ref 变量。
✅ 修复后的 dashboard.js（store）
import { defineStore } from "pinia";
import { useFetch } from "#app";
import { useAuthStore } from "./auth";
const baseUrl = import.meta.env.VITE_API_KEY + "/hr/widgets/dashboard";
export const useDashboardStore = defineStore("dashboard", () => {
const authStore = useAuthStore();
const { getToken } = authStore;
const widgets = ref([]);
const fetchedWidgets = ref(false);
// ✅ 改为返回一个可 await 的 Promise，显式 resolve 响应数据
async function loadWidgets() {
const { data, error, execute } = useFetch(baseUrl + "/list/get", {
headers: {
Accept: "application/json",
Authorization: "Bearer " + getToken,
},
// ❌ 移除 onResponse —— 它是副作用钩子，不参与 Promise 流程
// ✅ 改用 execute() + await data 实现可控等待
});
try {
await execute(); // ✅ 触发请求并等待完成
if (error.value) throw error.value;
widgets.value = data.value || [];
fetchedWidgets.value = true;
return widgets.value; // ✅ 明确返回处理后的数据
} catch (err) {
throw showError({
statusCode: 401,
statusMessage: "Error: - " + (err?.message || "Unknown error"),
fatal: true,
});
}
}
return {
widgets, // ✅ 直接返回 ref，不在此处解构
loadWidgets,
fetchedWidgets, // ✅ 同上
};
});✅ 修复后的组件逻辑（<script setup>）</script>
<script setup>
import { ref, onMounted } from "vue";
import { useDashboardStore } from "~/stores/dashboard";
import { useCandidatesStore } from "~/stores/candidates";
const props = defineProps({
page: {
type: String,
required: true,
},
});
const dashboardStore = useDashboardStore();
const candidatesStore = useCandidatesStore();
// ✅ 使用 ref 存储 layout/index（确保响应式）
const layout = ref([]);
const index = ref(0);
onMounted(async () => {
try {
const values = await getWidgets(); // ✅ 直接 await，无需 .then()
mapWidgetsData(values);
} catch (err) {
console.error("Failed to load widgets:", err);
}
});
const getWidgets = async () => {
switch (props.page) {
case "dashboard": {
// ✅ 关键：不使用解构！直接通过 store 实例访问 ref
if (!dashboardStore.fetchedWidgets.value) {
return await dashboardStore.loadWidgets(); // ✅ await 返回的数据
}
return dashboardStore.widgets.value; // ✅ 访问 .value 获取当前值
}
case "employees": {
// 同理，使用 candidatesStore.widgets / .fetchedWidgets / .loadWidgets()
const { loadWidgets, widgets, fetchedWidgets } = candidatesStore;
// ⚠️ 注意：此处若仍解构，同样会丢失响应性！应改为：
// if (!candidatesStore.fetchedWidgets.value) { ... }
// return candidatesStore.widgets.value;
break;
}
default:
return [];
}
};
const mapWidgetsData = (values) => {
if (!values || !Array.isArray(values.data)) return;
const itemsData = values.data;
layout.value = [];
itemsData.forEach((value) => {
try {
const position = JSON.parse(value.position);
layout.value.push({
...position,
i: value.id,
type: value.type,
});
} catch (e) {
console.warn("Invalid position JSON for widget", value.id, e);
}
});
index.value = values.last_index + 1;
};
</script>? 关键要点总结
- 禁止解构 ref：const { widgets } = store 会剥离响应性，必须始终通过 store.widgets.value 访问；
- useFetch 不是“即用型” Promise：它返回的是一个包含 execute() 方法的对象，需显式调用 await execute() 并检查 data.value；
- onResponse 是副作用钩子，非控制流节点：它在响应到达时同步执行，但不会影响外部 Promise 的 resolve 时间点，故不适合作为 await 的依据；
- 错误处理需统一：建议在 store 层捕获并抛出业务错误，在组件层用 try/catch 处理，避免静默失败；
- Nuxt 3 兼容性提示：useFetch 在服务端渲染（SSR）中默认惰性执行，如需首屏数据，请结合 useAsyncData 或 useFetch(..., { immediate: true })。
遵循以上模式，即可确保异步加载、状态更新与数据消费形成可靠的响应式链条，彻底规避 undefined 和竞态问题。
