👁 141 次阅读

Nuxt script setup 中 navigateTo 为何无法终止执行

来源：https://github.com/nuxt/nuxt/issues/23698

现象描述

在 Nuxt 3 的 <script setup> 块中连续调用 navigateTo 时，代码不会在第一次重定向后停止执行，后续逻辑仍会运行，最终页面停留在最后一次导航的目标地址。issue 中给出的最小复现如下：

<script setup lang="ts">
await navigateTo("/a")
await navigateTo("/b")
</script>

期望行为是导航到 /a 后停止，实测结果是先导航到 /a，随后继续跳到 /b 并停留在 /b。报告者所在环境为 Linux、Node v20.5.1、Nuxt 3.7.3、CLI 3.8.4、Nitro 2.6.3、yarn 1.22.19。带业务逻辑的典型场景更能说明问题：在 <script setup> 中先 await useFetch("/api/milk")，当返回数据为空时 await navigateTo("/a")，接着代码继续执行 await useFetch("/api/honey")，数据为空时又 await navigateTo("/b")。结果是先跳到 /a 再跳到 /b，而非在 /a 处终止。报告者还尝试过以下写法，结果均停留在 /b 而非 /a：

<script setup lang="ts">
await navigateTo("/a", { replace: true, external: true})
await navigateTo("/b", { replace: true, external: true})
</script>

<script setup lang="ts">
await navigateTo("/a", { replace: true})
await navigateTo("/b", { replace: true})
</script>

背景原因

在 Nuxt 2 时代，<script setup> 中可以用 return navigateTo() 来终止执行，但该写法已被废弃（见 issue 中引用的 https://github.com/nuxt/nuxt/issues/15002 ）。废弃之后，navigateTo 只返回一个 Promise，并不会中断函数控制流，因此调用它之后 setup() 仍会继续往下跑。关于修复方向，维护者 danielroe 在讨论中给出的判断是：这可以实现为一个编译器插件，在 navigateTo 之后从 setup() 函数中提前 return。这是目前讨论中唯一来自官方侧的实现思路，issue 仍处于 open 状态，官方尚未合入任何方案。

排查或量化方法

判断是否命中该问题，可对照以下特征：

<script setup> 中存在多个 await navigateTo 调用，最终落点是最后一个，而非第一个。
跳转目标由业务条件（如接口返回数组长度为 0）决定，期望「满足条件即终止」，实际跳转后 setup() 剩余逻辑照常执行。
使用 { replace: true }、{ external: true }、{ replace: true, external: true } 任一组合，均无法改变「跳转到最后一个目标」的结果。
重定向逻辑被抽取到 composable 中复用时问题更突出。据 issue 讨论，dulnan 描述其将 fetch 请求与重定向处理抽成 composable 供多个商品页组件调用，结果页面在重定向后继续渲染，整套逻辑失效。

该问题会被标注 🛠️ dx（开发者体验）与 🍰 p2-nice-to-have（优先级为「有则更好」），说明官方将其定位为体验类改进而非阻断性缺陷。截至 2025-06-10，OrbisK 将复现迁移到最新 v3 版本 Nuxt 后仍可重现，上报渠道为 StackBlitz：https://stackblitz.com/edit/github-jyzzpv9h?file=app.vue

完整解决方案（社区变通方案）

由于官方尚未提供框架层方案，issue 讨论中出现了若干社区侧的绕过手段，各自存在明显局限。

方案一：抛出自定义错误 + 全局插件捕获

据 issue 讨论，gmenunes 给出的做法是定义一个重定向辅助函数，在 navigateTo 之后主动抛出错误，并用 try/catch 兜住，从而阻止后续代码执行：

import type { RouteLocationRaw } from 'vue-router'

const useRedirectAndReturn = async (
  fn: (
    redirect: (args: RouteLocationRaw | undefined | null) => Promise<never>
  ) => Promise<any>
) => {
  const redirect = async (args: RouteLocationRaw | undefined | null) => {
    await navigateTo(args)
    throw new Error('Stop executing code')
  }

  try {
    // ...
  }
}

TheInnerParty 采用了同思路但更结构化的实现：定义 ForceRedirectError 类，并通过全局插件捕获该错误后导航到目标位置。

export class ForceRedirectError extends Error {
    constructor(message: string) {
        super(message)
        this.name = "ForceRedirectError"
    }
}

方案二：抛出任意错误（仅限 ssr: false）

据 issue 讨论，jrutila 给出的方案是在 await navigateTo 之后抛出任意错误，以中断 setup()：

仅在 ssr: false 时可用；
开启 SSR 时会返回 500 页面；
在无 SSR 模式下，也只在通过 nuxt-link 导航时有效；若在首次页面加载时抛出，页面加载会直接停止。

jrutila 提供了对应的 StackBlitz 复现该问题。

方案三：使用 external: true

据 issue 讨论，manchenkoff 的场景是在自定义 $fetch 客户端插件的 onResponse 拦截器中，当 API 返回 503 时触发重定向。其找到的唯一变通方式是使用 external 标志，避免后续 navigateTo 覆盖前一次调用：

await navigateTo('/page-for-503', { external: true })

方案对比

方案	核心做法	适用条件	主要局限
自定义错误 + 全局插件	封装 redirect 抛错，插件捕获后导航	需自行维护错误类与插件	属应用层自建机制，非框架能力
抛任意错误	`await navigateTo` 后 throw	仅 `ssr: false`	开 SSR 返回 500；首次加载即抛会中断加载
`external: true`	给 `navigateTo` 加 external 标志	拦截器等特定场景	仅解决覆盖问题，不终止执行

表中方案均来自 issue 讨论中的用户反馈，属社区结论，官方未确认。

常见错误排查

跳转落在最后一个目标：检查 <script setup> 中是否存在多个 await navigateTo。控制流不会在第一个调用处停止，这是该 issue 的核心表现。
加了 replace / external 仍无效：据报告者实测，{ replace: true }、{ external: true } 及二者组合都无法改变最终落点，不要指望这些参数解决终止问题。
抽取成 composable 后整体失效：据 dulnan 反馈，将重定向逻辑放进 composable 会导致页面继续渲染、逻辑不生效。若采用此结构，需配套错误抛出机制。
使用 throw 后在 SSR 下出现 500 页面：jrutila 明确指出该变通仅适用于 ssr: false，开启 SSR 会触发 500 页面。
在 definePageMeta 中重复声明变量：据 jlumia 反馈，为阻止 script setup 继续执行，被迫在 definePageMeta 中重新声明用到的变量，代码可维护性下降。

实践建议

在 <script setup> 中避免串联多个依赖条件的 await navigateTo，重定向逻辑尽量收敛到单一出口，减少覆盖风险。
若必须使用抛错方案，注意其与 SSR 的冲突：jrutila 的结论是该方式只在 ssr: false 下成立，开启 SSR 会得到 500 页面。
通过全局插件统一捕获重定向错误（如 TheInnerParty 的 ForceRedirectError 模式），可避免在每个页面重复写 try/catch。
关注官方对 danielroe 提出的编译器插件方案的推进情况。截至最后更新，该思路尚未合入，issue 状态仍为 open，社区在最新 v3 版本上仍可复现（OrbisK，2025-06-10）。
若需求来自 Nuxt 2 迁移，参考 jlumia 的经验：大量 definePageMeta 声明会显著增加改造量，建议提前评估重定向逻辑的组织方式。

FAQ

Q：为什么 Nuxt 3 不再支持 return navigateTo()？ A：据 issue 引用，该写法已被废弃，详见 https://github.com/nuxt/nuxt/issues/15002 。废弃后 navigateTo 仅返回 Promise，不中断控制流。 Q：官方给出的修复方向是什么？ A：维护者 danielroe 表示可以实现为编译器插件，在 navigateTo 之后从 setup() 提前 return。该方案尚未落地，issue 仍为 open。 Q：这个 issue 现在是什么状态？ A：状态为 open，创建于 2023-10-16，最后更新 2023-10-16，标签为 🛠️ dx 与 🍰 p2-nice-to-have，讨论共 12 条。截至 2025-06-10 仍有用户在最新 v3 版本上复现。 Q：有没有不依赖框架改动的可行做法？ A：据 issue 讨论，可封装 navigateTo 后在内部抛错并由全局插件捕获（gmenunes、TheInnerParty 的做法）；或仅在 ssr: false 下于 await navigateTo 后抛任意错误（jrutila 的做法）。这些均为社区结论，官方未确认。 Q：使用 external: true 能解决终止问题吗？ A：据 manchenkoff 反馈，external 标志可在其 $fetch 拦截器场景下避免后续 navigateTo 覆盖，但报告者实测该参数并不解决「不终止执行」的根本问题。