先解决Cannot find module '@/utils/airtable'的错误 #

我之前也踩过类似的坑，一步步排查应该能搞定：

• 第一步：确认文件路径与大小写
  先检查项目根目录下是否真的存在utils/airtable.ts（或者utils/airtable/index.ts），而且要注意文件名大小写——TypeScript对文件名是严格区分大小写的，比如文件名叫Airtable.ts但你导入写的airtable，就会触发这个错误。

• 第二步：验证tsconfig配置是否生效
  你的tsconfig配置逻辑上没问题，但要注意两个细节：

  1. tsconfig.json必须放在项目根目录，不能嵌套在子文件夹里；
  2. 修改tsconfig后，一定要重启Next.js开发服务器——配置变更需要重新加载才能生效，这是很多人容易忽略的点。
     如果还是不行，可以试试把paths里的路径前的斜杠去掉，改成：

  {
    "compilerOptions": {
      "baseUrl": ".",
      "paths": {
        "@/api/*": ["pages/api/*"],
        "@/utils/*": ["utils/*"]
      }
    }
  }
  

  （因为baseUrl已经设为.了，不需要再加开头的斜杠）

• 第三步：检查文件导出是否正确
  打开utils/airtable.ts，确认你确实给对应的类型和函数加上了export关键字：

  // 必须有export才能被外部导入
  export type Post = {
    // 你的类型定义
  };
  
  export const savePost = () => {
    // 函数逻辑
  };
  

  如果漏了export，TypeScript也会提示找不到模块里的导出项。

• 第四步：排除别名问题，用相对路径测试
  暂时不用别名，改用相对路径导入试试，比如你的组件在pages/posts.tsx，就写：

  import type { Post } from '../utils/airtable';
  import { savePost } from '../utils/airtable';
  

  如果这样能成功，说明是别名配置的问题。对于旧版本的Next.js，可能需要在next.config.js里手动配置webpack别名：

  /** @type {import('next').NextConfig} */
  const nextConfig = {
    webpack: (config) => {
      config.resolve.alias = {
        ...config.resolve.alias,
        '@/utils': path.resolve(__dirname, 'utils'),
        '@/api': path.resolve(__dirname, 'pages/api'),
      };
      return config;
    },
  };
  
  module.exports = nextConfig;
  

  记得顶部要引入path模块：const path = require('path');

关于工具/API逻辑文件的存放位置 #

在Next.js + TypeScript项目中，这类通用的API配置、工具函数、类型定义，最常用也最规范的存放方式是：

• 根目录下的utils/文件夹：这是社区的通用做法，所有不依赖组件、跨页面复用的工具函数、API封装都放在这里，比如你的airtable操作逻辑就很适合放在这里。
• 如果有大量类型定义：可以单独在根目录创建types/文件夹，把通用类型（比如Post）放在这里，比如types/airtable.ts，然后在utils/airtable.ts里导入类型，这样结构更清晰。
• 业务相关的工具：如果是和特定业务模块绑定的工具（比如仅在博客页面使用的函数），可以放在features/blog/utils/这样的目录下，适合大型项目做模块化拆分。

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