在前端TypeScript项目开发中，经常会遇到既有传统JSX组件，又有TypeScript编写的TSX组件的情况，很多开发者会担心两者无法兼容，实际上只要掌握正确的配置和写法，就能实现两者的无缝集成。
JSX与TSX的核心差异
JSX是JavaScript的语法扩展，允许在JS代码中直接写类HTML结构，本身没有类型约束；TSX是TypeScript对JSX的扩展，在支持JSX语法的基础上，增加了TypeScript的类型检查能力，可以在组件定义、props传递等环节做类型校验，减少运行时错误。
两者的语法大部分是通用的，主要区别体现在类型相关的写法上，比如TSX中定义组件时需要标注props的类型，而JSX则不需要。
TypeScript项目的基础配置
要实现两者的集成，首先需要调整项目的tsconfig.json配置，确保TypeScript能够正确识别和处理JSX/TSX文件。
关键配置项说明
| 配置项 | 取值 | 作用 |
|---|---|---|
| jsx | react-jsx 或 preserve | 指定JSX的编译方式，react-jsx会编译为现代React JSX运行时，preserve会保留JSX结构交给后续构建工具处理 |
| allowJs | true | 允许TypeScript项目引入JS文件，是集成JSX组件的必要配置 |
| checkJs | false 或 true | 是否对JS文件做类型检查，设为false可以减少旧JSX文件的类型报错，设为true则可以做更严格的校验 |
| esModuleInterop | true | 兼容CommonJS和ES模块的导入导出，避免组件引入时的模块报错 |
下面是一个基础的tsconfig.json配置示例：
{
"compilerOptions": {
"target": "es6",
"module": "esnext",
"jsx": "react-jsx",
"allowJs": true,
"checkJs": false,
"esModuleInterop": true,
"strict": true,
"moduleResolution": "node"
},
"include": ["src/**/*"],
"exclude": ["node_modules"]
}组件互调的实现方式
TSX组件调用JSX组件
TSX组件要调用JSX组件，只需要在引入时正确指定路径，TypeScript会自动识别JS文件。如果担心类型问题，可以给JSX组件添加JSDoc注释来补充类型信息，TypeScript会读取这些注释做类型校验。
比如有一个JSX编写的Button组件：
// src/components/Button.jsx
import React from 'react';
/**
* @param {Object} props
* @param {string} props.text - 按钮文本
* @param {() => void} props.onClick - 点击事件回调
*/
export default function Button(props) {
return <button onClick={props.onClick}>{props.text}</button>;
}在TSX组件中调用它的写法如下：
// src/pages/Home.tsx
import React from 'react';
import Button from '../components/Button.jsx';
const Home: React.FC = () => {
const handleClick = () => {
console.log('按钮被点击了');
};
return (
<div className="home">
<h2>首页</h2>
<Button text="点击我" onClick={handleClick} />
</div>
);
};
export default Home;JSX组件调用TSX组件
JSX组件调用TSX组件时，不需要额外做特殊配置，正常引入即可。因为TSX编译后本质是JS代码，JSX组件可以正常识别。如果JSX组件需要做类型提示，同样可以通过JSDoc注释来关联TSX组件的props类型。
比如有一个TSX编写的Input组件：
// src/components/Input.tsx
import React from 'react';
interface InputProps {
value: string;
onChange: (val: string) => void;
placeholder?: string;
}
const Input: React.FC<InputProps> = (props) => {
return (
<input
value={props.value}
onChange={(e) => props.onChange(e.target.value)}
placeholder={props.placeholder}
/>
);
};
export default Input;在JSX组件中调用的写法如下：
// src/components/Form.jsx
import React from 'react';
import Input from './Input.tsx';
export default function Form() {
const [name, setName] = React.useState('');
return (
<div className="form">
<label>姓名：</label>
<Input
value={name}
onChange={setName}
placeholder="请输入姓名"
/>
</div>
);
}常见问题与解决方案
- 引入文件时报路径错误：检查tsconfig.json的include配置是否包含了组件所在目录，同时引入时尽量写全文件后缀，避免构建工具解析错误。
- JSX组件传递props时TypeScript报错：如果是TSX调用JSX组件，给JSX组件补充JSDoc类型注释即可；如果是JSX调用TSX组件，检查TSX组件的props类型是否允许传入的值。
- 编译时报JSX语法错误：检查tsconfig.json的jsx配置是否正确，同时确保所有JSX/TSX文件的后缀名和实际语法匹配，JSX文件不要写TypeScript特有的类型语法。
最佳实践建议
如果是新开发的项目，建议统一使用TSX编写组件，充分发挥TypeScript的类型优势；如果是旧项目迁移，可以逐步将JSX组件改写为TSX，不需要一次性全部替换，按照上述方法让两者共存，降低迁移成本。另外可以在项目规范中明确要求新增组件使用TSX，存量组件按需改造，这样既能保证项目稳定性，又能逐步提升代码质量。
TypeScriptJSXTSX组件集成前端开发修改时间：2026-06-02 05:08:15