Vue3 使用 async setup() 引发组件空白、模板不渲染问题

核心认知偏差：Suspense的作用层级搞反了 #

Vue 3 对async setup()的处理有明确规则：

• 只要setup()函数加了async关键字，它就会返回一个Promise，这个组件就成为了异步组件
• 这类异步组件必须被放在外层父级的<Suspense>的默认插槽中，由外层Suspense来负责等待Promise的状态切换：等待期间渲染fallback内容，resolve之后再渲染组件本身的模板

你现在的写法完全颠倒了这个层级关系：
Login.vue本身是带async setup的异步组件，但它的父级根本没有用Suspense包裹它，反而把<Suspense>写在了Login组件自己的模板内部。这就导致Login组件的setup Promise没有对应的外层承接，Vue检测到这种情况时，会直接把整个Login组件渲染成空白注释节点，根本不会执行它模板里的任何内容——这就是你看到全页面空白、连静态写的<h1>LOGIN</h1>都显示不出来的核心原因。

简单类比：你要等的快递（带async setup的Login组件）到了小区门口，但是你家（Login的模板内部）自己设了个取件等候区（模板里的Suspense），物业（外层父级）根本没把快递递进来，你家的等候区自然永远用不上。

其他隐藏的小问题 #

• 在useLogin的login方法的catch块里返回new Error()，这个操作并不会中断setup的等待流程，反而会让await login()永远正常resolve成一个Error实例，接口报错时既不会中断渲染流程，也没法触发Suspense的错误处理
• 你模板里Suspense包裹的<div>My token: {{ token }}</div>本身是普通的同步DOM节点，根本不需要Suspense做异步协调，这个Suspense的位置从一开始就没有存在的意义

方案一：匹配async setup + Suspense的标准用法 #

把Suspense从Login组件内部移到它的直接父级位置，由父级的Suspense来承接Login的异步状态：

1. 修改父级容器的代码（以路由页面为例，通常写在App.vue的路由出口位置）：

<template>
  <Suspense>
    <template #default>
      <!-- 所有路由下的异步组件都会被这个Suspense接管 -->
      <router-view />
    </template>
    <template #fallback>
      <div>页面加载中...</div>
    </template>
  </Suspense>
</template>

2. 删掉Login.vue模板里多余的Suspense，简化代码：

<template>
  <h1>LOGIN</h1>
  <div>My token: {{ token }}</div>
</template>

<script>
import useLogin from '../modules/users';
export default {
  async setup() {
    const { login, token } = useLogin();
    // 等接口请求完成、token赋值后，setup才会resolve
    await login();
    return { token };
  },
};
</script>

3. 修正useLogin里的错误处理逻辑，不要在catch块里返回Error：

const login = async () => {
  try {
    token.value = await api.userLoginToken({
      email: 'user@test.com',
      password: '123123',
    });
    console.log(token.value);
  } catch (error) {
    console.log('error:', error);
    // 接口报错时直接抛出异常，让外层的错误边界/Suspense可以捕获处理
    throw error;
  }
};

这种写法的实际效果是：进入Login页面时，外层Suspense先展示加载提示，等接口请求完成、token赋值成功后，自动切换显示Login的完整页面内容。

方案二：轻量写法（不需要Suspense特性时） #

如果只是想在页面初始化时拉取接口数据，完全没必要给setup加async，普通同步setup的写法就足够，这也是项目开发中最常用的方式：

<template>
  <h1>LOGIN</h1>
  <div>My token: {{ token }}</div>
  <div v-if="loading">加载中...</div>
</template>

<script>
import useLogin from '../modules/users';
export default {
  setup() {
    const { login, token, loading } = useLogin();
    // 不需要await，setup同步执行，初始化时自动触发请求就行
    login();
    return { token, loading };
  },
};
</script>

这种写法和你之前验证过的「去掉async、去掉await就能正常显示」的逻辑完全一致，不需要依赖Suspense的渲染协调，灵活性更高。

• 带async setup的组件，永远是Suspense默认插槽的内容，Suspense的层级必须比异步组件高，不能把Suspense写在异步组件自己的模板里
• 没有被外层Suspense包裹的async setup组件，会直接渲染为空白节点，导致整页无内容
• 仅做初始化接口请求的场景，优先用同步setup+状态控制的写法，没必要强行套用async setup的模式

内容的提问来源于stack exchange，提问作者NuoNuo LeRobot