Nuxt 3 在开发体验上的一个明显提升就是组合式函数（Composables）自动导入。只要把文件放进 composables 目录，并按照 use 开头的命名规范导出函数，组件里就能直接使用而不需要写 import。但自动导入并不等于自动获得类型支持。很多项目在默认配置下一切正常，一旦把组合式函数挪到 src/composables 或自定义目录，TypeScript 立即开始报隐式 any，甚至 Cannot find name。根本原因在于自动导入的类型能力并不是 Nuxt 编译器实时推导出来的，而是依赖构建阶段生成的声明文件。
一、自动导入类型生成的底层逻辑
Nuxt 3 的自动导入能力来自 unimport。这个模块会扫描配置项 imports.dirs 中列出的目录，读取每个文件的导出符号，然后生成 .nuxt/types/imports.d.ts 文件。开发服务器启动时会执行一次扫描，手动运行 npx nuxi prepare 也会强制重新生成。这个声明文件的核心作用，就是告诉 TypeScript 在全局作用域中存在 useFoo、useBar 这样的标识符，并且它们的类型与原始模块中的导出完全一致。
打开 .nuxt/types/imports.d.ts 可以看到类似下面的结构。Nuxt 并没有把所有组合式函数的实现复制过来，而是通过 typeof import 的方式引用源文件。这样当你修改 useApi 的参数或返回值时，只要重新生成声明，类型就会同步更新，不需要维护两份类型定义。理解了这一点，就很容易明白为什么自定义目录后类型会消失：扫描列表里没有那个目录，声明文件自然也不会包含对应的全局符号。
// .nuxt/types/imports.d.ts 片段
declare global {
const useApi: typeof import('../composables/useApi')['useApi']
const useUserStore: typeof import('../composables/useUserStore')['useUserStore']
}
export {}
默认情况下，Nuxt 会扫描项目根目录下的 composables 和 utils 目录，并且支持 index 文件聚合导出。这意味着 composables/index.ts 里的命名导出同样会被自动导入。但如果目录层级比较深，例如 composables/api/useApi.ts，则需要在 imports.dirs 中使用 glob 表达式明确包含子目录，否则深层文件可能被忽略。
二、为自定义目录配置类型声明
假设项目结构使用 src 作为源码根目录，组合式函数位于 src/composables，此时默认扫描不会覆盖到它。需要修改 nuxt.config.ts 中的 imports.dirs。配置项接受字符串数组，每一项可以是具体目录，也可以是 glob 模式。注意路径基于项目根目录，而不是配置文件所在目录。
// nuxt.config.ts
export default defineNuxtConfig({
imports: {
dirs: [
'composables',
'src/composables',
'src/composables/**/*.ts',
],
},
})
这里同时保留了默认 composables 和新路径，也可以只写自己需要的目录。glob 写法 src/composables/**/*.ts 表示递归匹配所有 TypeScript 文件，适合目录有多层嵌套的场景。如果只想扫描一级子目录，可以使用 src/composables/*/ 这类模式，但要注意 unimport 对 glob 的支持细节，通常 ** 方式最稳妥。
修改完配置后，必须执行一次 npx nuxi prepare，让 Nuxt 重新生成 .nuxt/types 目录。很多人改完配置后只重启了开发服务器，发现类型仍然缺失，就是因为没有等声明文件更新，或者编辑器缓存了旧的 TS Server 状态。建议在 package.json 的 postinstall 脚本中加上 nuxi prepare，这样每次安装依赖后都会自动生成类型。
# 手动重新生成类型声明 npx nuxi prepare # 执行类型检查 npx nuxt typecheck
如果不想依赖自动扫描，也可以手动创建类型声明文件。比如在项目根目录创建 types/composables.d.ts，通过 declare global 暴露全局函数类型。这种方式可控性更强，但每个新增的 Composable 都要手动补充声明，适合自动扫描无法满足要求的场景。
// types/composables.d.ts
import type { UseApiReturn } from '../src/composables/useApi'
declare global {
const useApi: (url: string) => UseApiReturn
}
export {}
手动声明的缺点是失去自动同步能力，一旦 useApi 的参数或返回值发生变化，而声明文件忘了更新，类型反而会误导开发。因此更推荐优先使用 imports.dirs 配合 nuxi prepare 的方案，只有在目录结构非常特殊、扫描规则无法覆盖时才考虑手动声明。
三、嵌套导出与类型推导的细节
在组织 Composables 时，很多人喜欢按业务域分目录，比如 composables/user/useProfile.ts、composables/order/useCart.ts。自动导入能否识别这些嵌套文件，取决于 imports.dirs 是否匹配到它们。如果路径匹配成功，unimport 会为每个命名导出生成全局类型，类型推导不会因为嵌套而丢失。
但是，当目录中包含 index.ts 时，需要留意重复导出问题。例如 composables/user/index.ts 导出了 useProfile，同时 composables/user/useProfile.ts 也被扫描到并导出了 useProfile，这时全局会出现两个同名声明，可能导致编辑器提示重定义。解决方法通常是让 imports.dirs 只指向需要自动导入的索引文件，或者使用更精确的 glob 模式。
// composables/user/index.ts
export { useProfile } from './useProfile'
export type { Profile } from './useProfile'
推荐在 Composable 文件中使用命名导出，而不是默认导出。Nuxt 的自动导入机制主要面向命名导出设计，默认导出虽然有些情况下也能被扫描到，但类型声明生成和开发体验并不稳定。统一使用 export function useXxx 的形式，也能让 IDE 的自动补全和跳转更可靠。
涉及泛型时，类型推导同样可以保留。例如 useFetchLike 接收泛型参数 T，生成的全局声明会引用原始签名，调用时传入具体类型即可获得完整提示。关键在于声明文件中的 typeof import 是直接引用源模块，不会丢失泛型信息。
四、类型不生效的排查思路
如果配置和命令都执行了，编辑器仍然报 Cannot find name useXxx，首先检查 tsconfig.json 是否正确扩展了 Nuxt 生成的配置。Nuxt 3 会在 .nuxt 目录下生成 tsconfig.json，其中包含 types 和 include 设置。项目根目录的 tsconfig 通常只需 extends 这个文件。
{
"extends": "./.nuxt/tsconfig.json"
}
如果根目录的 tsconfig 没有 extends，TypeScript 就不知道要去读取 .nuxt/types 下的声明文件。需要手动在 include 中添加 .nuxt/types 或者使用官方推荐的 extends 方式。VSCode 用户还要注意 Volar 是否接管了 Vue 和 TypeScript 文件，如果语言服务没有启用 Take Over Mode，可能会出现 Vue 文件中类型正常但 TS 文件中不正常的情况。
另一个常见原因是 TS Server 缓存。执行 npx nuxi prepare 之后，声明文件已经更新，但编辑器的 TypeScript 服务还缓存着旧状态。在 VSCode 中可以通过命令面板运行 TypeScript: Restart TS Server 来刷新。WebStorm 则需要开启 Nuxt 支持并在 Settings 中勾选 Use TypeScript Server。如果项目是团队协作 clone 下来的，.nuxt 目录通常被 gitignore 忽略，需要先运行 npx nuxi prepare 再启动开发服务器。
最后，检查组合式函数文件本身的命名。自动导入默认只识别 use 开头的文件或导出，如果文件叫 profile.ts 且导出函数也叫 getProfile，那么即使目录在扫描范围内，也不会生成 useProfile 这个全局符号。统一命名规范可以避免大量隐蔽的类型问题。
Nuxt 3TypeScript自动导入类型修改时间：2026-10-01 15:16:17