1. 理解JSX与TSX的共存性
在现代前端开发中，尤其是在react生态系统中，typescript (tsx) 和javascript (jsx) 组件可以很好地共存。typescript是javascript的超集，这意味着合法的javascript代码通常也是合法的typescript代码（尽管可能需要类型推断或声明文件）。因此，将一个纯jsx文件编写的组件导入到tsx文件中是完全可行的，并且通常不会引发语法层面的问题。
然而，当TypeScript项目尝试导入一个.jsx文件时，如果TypeScript编译器没有被正确配置，它可能无法识别该文件的模块声明，从而抛出类似“Cannot find declaration for module”的错误。这并非表示JSX和TSX不能混合使用，而是表明TypeScript环境需要额外的指引来处理非.ts或.tsx扩展名的文件。
2. 核心问题与解决方案：tsconfig.json 配置
“无法找到模块声明”的错误通常是由于TypeScript编译器不知道如何解析或处理.jsx文件引起的。解决这个问题的关键在于正确配置项目的tsconfig.json文件，告知TypeScript编译器如何处理JavaScript和JSX文件。
2.1 关键配置项
以下是确保JSX组件在TSX项目中正常导入所需的几个核心tsconfig.json配置项：
- allowJs: true: 这个选项告诉TypeScript编译器允许编译JavaScript文件（包括.js和.jsx）。这是集成JSX组件的基础。
- jsx: "react" 或 "react-jsx": 这个选项指定了TypeScript如何处理JSX语法。对于React项目，通常设置为"react"（旧版）或"react-jsx"（新版，无需手动导入React）。
- moduleResolution: "node": 确保模块解析策略与Node.js的解析机制一致，这对于大多数前端项目来说是标准的。
- include 和 exclude: 这些选项定义了TypeScript编译器应该包含和排除的文件或目录。确保你的.jsx文件所在的目录被include，并且没有被exclude。
2.2 示例 tsconfig.json 配置
{
"compilerOptions": {
"target": "es2018", // 目标JavaScript版本
"lib": ["dom", "dom.iterable", "esnext"], // 包含的库文件
"allowJs": true, // 允许编译JavaScript文件
"skipLibCheck": true, // 跳过声明文件的类型检查
"esModuleInterop": true, // 允许CommonJS和ES模块之间的互操作
"allowSyntheticDefaultImports": true, // 允许从没有默认导出的模块中合成默认导入
"strict": true, // 启用所有严格类型检查选项
"forceConsistentCasingInFileNames": true, // 强制文件名大小写一致
"noFallthroughCasesInSwitch": true, // 禁止switch语句中出现穿透
"module": "esnext", // 模块化方案
"moduleResolution": "node", // 模块解析策略
"resolveJsonModule": true, // 允许导入.json文件
"isolatedModules": true, // 确保每个文件都可以安全地单独编译
"noEmit": true, // 不生成输出文件（由构建工具处理）
"jsx": "react-jsx", // JSX工厂，根据你的React版本选择 "react" 或 "react-jsx"
"baseUrl": "./", // 用于解析非相对模块名称的基目录
"paths": { // 路径映射，用于处理别名导入
"@/*": ["src/*"]
}
},
"include": [
"src/**/*.ts",
"src/**/*.tsx",
"src/**/*.js",
"src/**/*.jsx" // 明确包含所有JSX文件
],
"exclude": [
"node_modules"
]
}注意事项：
- 确保include数组中包含了"src/**/*.js"和"src/**/*.jsx"，这样TypeScript编译器才能找到并处理这些文件。
- jsx选项的选择取决于你的React版本和项目配置。对于React 17及更高版本，使用"react-jsx"通常是推荐的，因为它支持新的JSX转换，无需在每个文件中手动import React from 'react'。
- 如果你的项目使用了路径别名（如@/shared/HText），请确保baseUrl和paths配置正确。
3. 示例：JSX组件与TSX组件的集成
让我们使用提供的Carousel.jsx和Samskaras.tsx作为示例，演示如何在配置正确的TypeScript项目中进行集成。
3.1 JSX组件定义 (Carousel.jsx)
这是一个纯JSX编写的轮播组件。请注意，它使用了import React from 'react'，如果jsx配置为"react-jsx"，这行可以省略。
import React from 'react'; // 如果tsconfig.json中jsx设置为"react-jsx"，此行可选
import { Swiper, SwiperSlide } from "swiper/react";
import 'swiper/css';
// import { sliderSettings } from './common.js'; // 假设 common.js 存在并导出 sliderSettings
// import data from './slider.json'; // 假设 slider.json 存在
// 简化示例数据和设置
const sliderSettings = {}; // 实际项目中应有具体配置
const data = [
{ name: "Item 1", image: "https://via.placeholder.com/150", description: "Description 1" },
{ name: "Item 2", image: "https://via.placeholder.com/150", description: "Description 2" }
];
const Carousel = () => {
return (
<div className='p-[1.5rem] w-[100%] overflow-hidden relative'>
<Swiper {...sliderSettings}>
{
data.map((card, i) => (
<SwiperSlide key={i}>
<div className='flex flex-col justify-center items-start gap-[0.6rem] p-4 rounded-[10px] max-w-[max-content] m-auto transition-all delay-300 ease-in'>
<img src={card.image} alt='samskaras'/>
<span>{card.name}</span>
<span>{card.description}</span>
</div>
</SwiperSlide>
))
}
</Swiper>
</div>
)
}
export default Carousel;3.2 TSX组件中导入JSX组件 (Samskaras.tsx)
现在，我们可以在TSX文件中直接导入并使用Carousel组件，就像导入其他TSX组件一样。
import HText from '@/shared/HText';
import { SelectedPage } from '@/shared/types'
import { motion } from 'framer-motion';
import Carousel from './Carousel'; // 从JSX文件导入Carousel组件
type Props = {
setSelectedPage: (value: SelectedPage) => void;
}
const Samskaras = ({setSelectedPage}: Props) => {
return (
<section id='samskaras' className='w-full bg-primary-100 py-40'>
<motion.div
onViewportEnter={() => setSelectedPage(SelectedPage.Samskaras)}
>
<motion.div
className='mx-auto w-5/6'
initial="hidden" whileInView="visible" viewport={{ once: true, amount: 0.5 }} transition={{ duration: 0.5 }} variants={{ hidden: {opacity: 0, x: -50}, visible: {opacity: 1, x: 0}}}
>
<div className='md:w-3/5'>
<HText>
SAMSKARAS
</HText>
<p className='py-5'>
Fringilla a sed at suspendisse ut enim volutpat. Rhoncus vel est
tellus quam porttitor. Mauris velit euismod elementum arcu neque
facilisi. Amet semper tortor facilisis metus nibh. Rhoncus sit
enim mattis odio in risus nunc.
</p>
</div>
</motion.div>
{/* 在TSX中使用导入的JSX组件 */}
<Carousel />
</motion.div>
</section>
)
}
export default Samskaras4. 常见问题与故障排除
- 文件路径或扩展名错误: 确保导入路径正确，并且文件扩展名（.jsx）没有被错误地省略或写错。在大多数情况下，导入时可以省略扩展名，但如果存在同名.ts/.tsx文件，可能会导致混淆。
- 未导出组件: 确保你的JSX文件正确地导出了组件（例如export default Carousel;）。
- TypeScript缓存问题: 有时，即使配置正确，IDE或构建工具的TypeScript语言服务可能仍使用旧的配置缓存。尝试重启你的开发服务器或IDE。
- 构建工具配置: 如果你使用的是Webpack、Rollup、Vite等构建工具，确保其配置（例如Babel或SWC的配置）也支持处理JSX文件。通常，这些工具会读取tsconfig.json，但有时需要额外的插件或预设。
- 类型声明缺失: 对于第三方JSX库，如果它们没有附带.d.ts类型声明文件，你可能需要手动创建声明文件（例如declare module 'some-jsx-library';）或安装@types/some-jsx-library。对于你自己项目中的JSX文件，allowJs: true通常足以让TypeScript推断其类型。
5. 总结
在TypeScript项目中集成JSX组件是一个常见的需求，并且通过正确配置tsconfig.json文件可以轻松实现。关键在于启用allowJs和jsx选项，并确保include路径覆盖了所有相关的JSX文件。一旦配置妥当，TypeScript编译器将能够无缝处理.jsx文件，允许开发者在同一个项目中灵活地使用JSX和TSX，从而充分利用两者的优势。遵循本文提供的配置和示例，你将能够有效地解决“无法找到模块声明”的问题，构建出健壮且可维护的混合语言项目。
