Nuxt 3 项目中，服务端文件（如 server/api/xxx.ts）使用路径别名（alias）时经常报 Cannot find module 错误，主要原因通常是 alias 配置只对客户端或构建工具生效，而未正确传递到 Nitro 服务端构建流程。下面按照场景说明配置方法和检查要点。

在 `nuxt.config.ts` 中添加 `alias` 属性，例如：`alias: { '@': '/path/to/src', '~': '/path/to/src' }`。注意路径应为绝对路径，推荐使用 `resolve`（需从 `path` 导入）动态获取，如 `alias: { '@': resolve(__dirname, './') }`。配置后重启开发服务器，并确保 tsconfig.json 中的 `paths` 与之同步，否则 TypeScript 类型检查可能报错但不会影响运行。

验证 alias 是否生效，可在任意服务端文件（如 `server/api/xxx.ts`）中打印 `import.meta.resolve('@/components/xxx')` 或者直接尝试导入，观察是否抛出错误。另一种方式是构建后检查 `.output/server/chunks/` 下的文件，搜索别名对应的路径是否已被替换为真实路径。如果出现 `undefined` 或原始别名，说明 `nuxt.config` 中的 alias 并未被服务端构建流程正确读取。

适用场景

Alias 适合需要简化深层目录导入的场合，例如用 @/components/Button 代替 ../../../components/Button。但仅在编译阶段生效，对运行时动态导入（如变量拼接路径）无效。如果你的服务端报错仅出现在构建后或开发服务器启动时，alias 配置受阻是常见原因。

操作建议

在 nuxt.config.ts 中添加 alias 属性，例如：alias: { '@': '/path/to/src', '~': '/path/to/src' }。注意路径应为绝对路径，推荐使用 resolve（需从 path 导入）动态获取，如 alias: { '@': resolve(__dirname, './') }。配置后重启开发服务器，并确保 tsconfig.json 中的 paths 与之同步，否则 TypeScript 类型检查可能报错但不会影响运行。

这里的关键是 resolve(__dirname, './') 得到的是项目根目录的绝对路径。如果项目结构特殊（例如 monorepo），需要根据实际情况调整。另外，alias 必须写在 nuxt.config 顶层，而不是嵌套在 vite 或 webpack 下，否则 Nitro 服务端构建可能忽略它。

检查方法

验证 alias 是否生效，可在任意服务端文件（如 server/api/xxx.ts）中打印 import.meta.resolve('@/components/xxx') 或者直接尝试导入，观察是否抛出错误。另一种方式是构建后检查 .output/server/chunks/ 下的文件，搜索别名对应的路径是否已被替换为真实路径。如果出现 undefined 或原始别名，说明 nuxt.config 中的 alias 并未被服务端构建流程正确读取。

具体操作：先执行 npx nuxi build，然后打开 .output/server/chunks/ 目录，用 grep 搜索别名标识（如 @/）。如果找到 @/ 保留未替换，说明 alias 配置未生效。此时需要检查 nuxt.config 中 alias 的写法，以及是否启用了 nitro.alias（见下一节）。

常见坑

一个常见陷阱是只配置了 vite.alias 但忽略了顶层 alias。Nuxt 3 的 alias 配置应直接放在 nuxt.config 的顶层，而非嵌套在 vite 或 webpack 内部。此外，server/ 目录下的文件与 pages 和 components 共享同一个 alias 配置，但若在 nitro 的 plugins 或 handlers 中使用了别名，可能需要额外配置 nitro.alias 才能生效。

我的经验是：如果你已经在 vite.alias 下配置了别名，并且客户端正常，但服务端依然报错，优先检查顶层 alias 是否遗漏。另外，如果用了 nitro 的插件或自定义 handler，nuxt.config 的顶层 alias 可能不会被继承，这时需要显式添加 nitro: { alias: { '@': resolve(__dirname, './') } }。

风险边界

Alias 配置仅在编译构建阶段生效，不会影响运行时动态导入。因此，对于使用 require() 或动态 import() 且路径包含变量拼接的场景，别名可能无法正确解析。此外，如果项目启用了 typescript 的 strict 模式，alias 路径必须与 tsconfig.json 中的 paths 绝对一致，否则编译可能抛出 Cannot find module 的错误，但构建依然可能成功，导致运行时错误难以定位。

建议在配置完成后，先用 nuxi typecheck 检查类型错误，再构建测试。如果构建成功但服务端运行时报模块找不到，大概率是运行时动态导入问题，需要改用静态导入或完全路径。

最后的检查清单

• 确认 nuxt.config 顶层有 alias 且路径为绝对路径。
• 确认 tsconfig.json 的 paths 与 alias 一致（可选，但推荐）。
• 构建后检查 .output/server/chunks/ 确认别名已被替换。
• 如果使用 Nitro 插件或自定义 handler，检查是否需要配置 nitro.alias。
• 避免在动态导入中使用别名。