在TypeScript项目里开发或使用JSX组件时，经常会遇到导入组件后类型报错、模块无法识别的问题，这些问题大多和模块声明缺失、TS配置不当有关。下面我们就从实际场景出发，一步步梳理这类问题的解决思路。
一、问题出现的常见场景
最常见的报错场景主要有这几类：
- 导入第三方JSX组件库时，提示找不到模块声明，或者组件类型无法识别
- 项目内自定义的JSX组件，在另一个文件中导入时，报模块不存在的错误
- 修改了JSX相关配置后，原本能正常导入的组件突然开始报错
二、模块声明缺失的解决方法
TypeScript需要明确的类型声明才能识别JSX组件，当模块声明缺失时，我们可以通过编写声明文件来补充类型信息。
1. 为第三方JSX组件添加声明
如果第三方库没有提供自带的TS声明，我们可以在项目根目录新建types文件夹，在里面创建对应的声明文件。比如要为一个叫custom-jsx-lib的库添加声明，可以新建types/custom-jsx-lib/index.d.ts，内容如下：
// 声明JSX元素的类型，适配React风格的JSX
import React from 'react';
declare module 'custom-jsx-lib' {
// 声明组件 props 类型
export interface CustomButtonProps {
text: string;
onClick?: () => void;
style?: React.CSSProperties;
}
// 声明组件，这里用函数组件形式定义
export const CustomButton: React.FC<CustomButtonProps>;
// 如果有其他组件，可以继续补充声明
}2. 项目内自定义JSX组件的声明
如果是项目内自己写的JSX组件，首先要确保组件文件有正确的导出，同时可以在组件同目录下或者全局声明文件中补充类型。比如我们有一个MyComponent.tsx组件：
// MyComponent.tsx
import React from 'react';
interface MyComponentProps {
title: string;
content: string;
}
const MyComponent: React.FC<MyComponentProps> = (props) => {
return (
<div>
<h3>{props.title}</h3>
<p>{props.content}</p>
</div>
);
};
export default MyComponent;如果导入时还是报错，可以检查是否在tsconfig.json中正确配置了声明文件的包含路径。
三、tsconfig.json的关键配置调整
tsconfig.json里的部分配置会直接影响JSX组件的解析，需要调整以下几个核心项：
| 配置项 | 可选值 | 作用说明 |
|---|---|---|
jsx | preserve、react、react-jsx、react-jsxdev | 指定JSX的编译方式，使用React生态一般选react-jsx，如果是其他框架根据框架要求调整 |
moduleResolution | node、classic、bundler | 指定模块解析策略，现在大部分项目选bundler或者node即可 |
typeRoots | 数组形式，填写声明文件目录 | 指定TypeScript加载类型声明的目录，把之前新建的types目录加进去，比如["node_modules/@types", "types"] |
include | 数组形式，填写需要包含的文件路径 | 确保组件文件和声明文件都在包含范围内，比如["src/**/*", "types/**/*"] |
四、常见问题排查思路
如果按照上面的方法配置后还是有报错，可以按照下面的步骤排查：
- 先检查导入路径是否正确，有没有写错文件名或者目录层级
- 确认声明文件的后缀是
.d.ts，并且内容符合TypeScript声明语法 - 重启TypeScript服务，有时候配置更新后需要重启IDE的TS服务才能生效
- 查看报错信息里提到的具体缺失的模块名称，针对性补充对应的声明
只要理清模块声明的逻辑，配合正确的tsconfig配置，绝大多数JSX组件导入的问题都可以顺利解决。
TypeScriptJSX模块声明tsconfig配置组件导入修改时间：2026-06-02 05:07:31