Cloudflare/Render部署时Import Aliases失效问题求助

问题场景 #

使用Vite 6.1 + TypeScript开发的项目，本地开发时@/*别名正常工作，但部署到Cloudflare或Render平台时，执行tsc && vite build命令出现TS2307错误，提示找不到@/components/xxx模块。

用户配置信息 #

tsconfig.json

{
  "compilerOptions": {
    // 其他省略配置
    "paths": {
      "@/*": ["./src/*"]
    }
  },
  "include": ["src"],
  "exclude": ["node_modules", "dist"],
  "references": [{ "path": "./tsconfig.node.json" }]
}

vite.config.ts

import { TanStackRouterVite } from "@tanstack/router-vite-plugin";
import react from "@vitejs/plugin-react";
import path from "path";
import { defineConfig } from "vite";
import tsconfigPaths from 'vite-tsconfig-paths';

export default defineConfig({
  plugins: [
    react({
      babel: {
        plugins: [["babel-plugin-react-compiler", { target: '19' }]]
      },
    }),
    TanStackRouterVite(),
    tsconfigPaths()
  ],
  resolve: {
    alias: {
      "@/": path.resolve(__dirname, "./src"),
    }
  }
});

部署报错信息

==> Build failed 😞
src/routes/__root.tsx(1,20): error TS2307: Cannot find module '@/components/header' or its corresponding type declarations.
src/routes/(landing)/_landing.tsx(2,20): error TS2307: Cannot find module '@/components/footer' or its corresponding type declarations.
$ tsc && vite build

核心修复步骤 #

1. 补全tsconfig的baseUrl配置
   TypeScript的paths规则必须配合baseUrl才能生效，本地开发时vite-tsconfig-paths插件可能自动兼容，但tsc单独编译时需要明确配置。在compilerOptions中添加：

"compilerOptions": {
  // 其他配置
  "baseUrl": ".", // 以项目根目录为基准路径
  "paths": {
    "@/*": ["./src/*"]
  }
}

2. 修正Vite的alias写法
   Vite的别名匹配规则不需要末尾斜杠，将resolve.alias改为：

resolve: {
  alias: {
    "@": path.resolve(__dirname, "./src"),
  }
}

或者保持与tsconfig一致的通配符写法：

resolve: {
  alias: {
    "@/*": path.resolve(__dirname, "./src/*"),
  }
}

3. 确保部署环境安装Dev依赖
   tsc属于开发依赖，Cloudflare Pages和Render默认可能只安装生产依赖，导致构建时找不到tsc命令：

• Cloudflare Pages：在package.json的scripts中，将build命令改为npm install && tsc && vite build，或在控制台构建设置中勾选"Install dev dependencies"。
• Render：在构建设置的"Build Command"中，先执行npm install --include=dev再执行构建，比如npm install --include=dev && tsc && vite build。

4. 检查tsconfig语法合法性
   确保tsconfig.json没有多余逗号或语法错误，比如原配置中paths对象末尾的冗余逗号可能导致解析异常，修正后保持JSON格式合规。

5. 本地预验证编译逻辑
   在本地执行tsc --noEmit命令，模拟部署时的编译流程，确认是否仍有相同错误。如果本地也报错，说明问题不在部署平台，而是本地配置本身存在疏漏。

额外注意事项 #

• 若使用tsconfig.node.json，确保该文件的配置兼容别名规则，或在主tsconfig.json的references中正确引用。
• Render平台需确保package.json中声明的typescript版本与本地开发一致，避免版本差异导致的编译问题。

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