TypeScript绝对导入报“依赖未找到”错误，寻求解决方法

配置与结构信息 #

tsconfig.json 配置 #

{
  "compilerOptions": {
    "baseUrl": "app",
    "jsx": "react",
    "target": "esnext",
    "module": "esnext",
    "moduleResolution": "node",
    "declaration": true,
    "strict": true,
    "esModuleInterop": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noImplicitAny": false,
    "lib": [
      "esnext", "dom"
    ]
  },
  
  "include": ["app"],
  "exclude": ["node_modules", "**/__tests__/*"]
}

项目文件夹结构 #

app
-> assets
   components
   contexts
   hooks
   models
   util
   ...
src
tests
...
tsconfig.json

注：app目录存放React UI代码，src为PHP代码

问题现象 #

在app/context/CurrentAccountContext.tsx中使用绝对导入：

import { useSessionAndLocalStorage } from 'hooks/useSessionAndLocalStorage';
import { useIsFirstRender } from 'hooks/useIsFirstRender';
import { Account } from 'models';
import { apiFetch } from '../util/apiFetch';
import { queryClient } from '../util/queryClient';

编译时报错：

Failed to compile with 2 errors          11:21:29 AM

These dependencies were not found:

* hooks/useIsFirstRender in ./app/context/CurrentAccountContext.tsx
* hooks/useSessionAndLocalStorage in ./app/context/CurrentAccountContext.tsx

To install them, you can run: npm install --save hooks/useIsFirstRender hooks/useSessionAndLocalStorage

异常点：models目录的绝对导入正常，但hooks目录的导入无法被识别，两个目录下均为TS文件，且无JS文件引用（正在从JS逐步迁移到TS）。

已尝试的无效方案 #

• 在tsconfig.json中配置paths属性
• 修改baseUrl为.、./、app等不同值
• 配置导入别名

排查思路与解决方案 #

排查方向 #

1. 检查hooks目录的文件命名与路径匹配

   • 确认hooks目录下是否存在useSessionAndLocalStorage.ts和useIsFirstRender.ts文件，注意操作系统的大小写区分（比如Windows不区分，但Linux/macOS区分）
   • 检查文件名拼写是否完全匹配，比如是否出现useSessionAndLocalstorage.ts（小写s）这类笔误

2. 验证tsconfig的文件覆盖范围

   • 确认hooks目录下的TS文件是否被include: ["app"]覆盖，可尝试显式添加app/hooks/**/*到include数组
   • 检查文件后缀是否为.ts或.tsx，.d.ts类型声明文件可能会有识别差异

3. 同步构建工具的路径配置

   • TypeScript的baseUrl和paths需要构建工具（Webpack/Vite/CRA等）同步支持，比如Create React App需要通过craco或react-app-rewired配置别名；Vite需要在vite.config.ts中设置resolve.alias
   • 排查是否在构建配置中意外排除了hooks目录，导致构建工具无法识别

4. 清理缓存

   • 删除TypeScript编译缓存文件（tsconfig.tsbuildinfo）或项目缓存目录（node_modules/.cache）
   • 重启开发服务器，避免缓存导致的路径识别异常

推荐解决方案 #

若文件路径和tsconfig配置无误，优先同步构建工具与TypeScript的别名配置：
以CRA+craco为例，在craco.config.js中添加：

const path = require('path');

module.exports = {
  webpack: {
    alias: {
      'hooks': path.resolve(__dirname, 'app/hooks'),
      'models': path.resolve(__dirname, 'app/models')
    }
  },
  typescript: {
    enableTypeChecking: true
  }
};

同时更新tsconfig.json的paths配置：

"compilerOptions": {
  "baseUrl": ".",
  "paths": {
    "hooks/*": ["app/hooks/*"],
    "models/*": ["app/models/*"]
  }
}

该配置可同时满足TypeScript类型检查与构建工具的路径解析需求。

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