配置TypeScript路径别名后，导入组件提示返回类型含undefined

问题场景 #

配置TypeScript路径别名缩短导入路径后，使用别名导入的组件被TypeScript提示返回类型包含undefined，无法作为JSX组件正常使用。

配置与代码 #

tsconfig.json 配置 #

{
  "compilerOptions": {
    "target": "ES2017",
    "lib": ["dom", "dom.iterable", "esnext"],
    "allowJs": true,
    "skipLibCheck": true,
    "strict": true,
    "forceConsistentCasingInFileNames": true,
    "noEmit": true,
    "esModuleInterop": true,
    "module": "esnext",
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "preserve",
    "incremental": true,
    "plugins": [
      {
        "name": "next"
      }
    ],
    "baseUrl": ".",
    "paths": {
      "@/*": ["*"],
      "@/locations/*": ["./app/(site)/(content)/events/locations/*"],
      "@/location/*": ["./app/(site)/(content)/events/locations/[location]/*"]
    }
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
  "exclude": ["node_modules", "create-env.js"]
}

导入代码 #

import {
  FacilityCard,
  LocationDescription,
  LocationGallery,
} from '@/location/components';

错误信息 #

'FacilityCard' cannot be used as a JSX component.
  Its return type 'Element | undefined' is not a valid JSX element.
    Type 'undefined' is not assignable to type 'Element | null'.ts(2786)

解决方案 #

1. 调整路径别名的匹配优先级 #

TypeScript解析路径别名时会按paths配置顺序匹配，更具体的路径规则必须放在通用规则前面。当前配置中@/*通用规则排在最前，会优先匹配所有@开头的路径，导致@/location/*的规则无法生效，可能解析到错误文件。

修改paths顺序：

"paths": {
  "@/locations/*": ["./app/(site)/(content)/events/locations/*"],
  "@/location/*": ["./app/(site)/(content)/events/locations/[location]/*"],
  "@/*": ["*"]
}

2. 验证导入路径正确性 #

在VSCode中按住Ctrl点击@/location/components，确认跳转的文件是预期的组件文件。若跳转至错误位置，需检查路径配置的准确性。

3. 检查组件返回值逻辑 #

若导入路径正确，检查FacilityCard组件代码，确保所有分支都返回有效的JSX元素或null，避免默认返回undefined：

错误示例：

const FacilityCard = () => {
  if (someCondition) {
    return <div>设施卡片</div>;
  }
  // 无返回值，默认返回undefined
};

修正后：

const FacilityCard = () => {
  if (someCondition) {
    return <div>设施卡片</div>;
  }
  // 明确返回null
  return null;
};

4. 重启TypeScript服务 #

Next.js或VSCode的TypeScript服务可能存在缓存，导致路径解析不及时生效。按Ctrl+Shift+P打开命令面板，输入Restart TypeScript Server重启服务后，再检查错误是否消失。

内容的提问来源于stack exchange，提问作者Frederick M. Rogers