未使用TypeScript，使用自研React组件包时遇模块声明文件缺失问题

API 探路者

2026-8-16

可能的原因及解决方法

组件包包含自动生成的TypeScript类型文件：即便你没写TS，组件包构建工具（比如tsc、@rollup/plugin-typescript）可能自动生成了.d.ts类型文件。create-react-app会自动解析node_modules里的类型文件，若这些文件有语法问题或不兼容配置，就会触发TS相关报错。可以检查组件包的输出目录（比如dist），如果不需要类型文件，修改构建配置关闭类型生成；如果需要，确保类型文件语法正确。
组件包依赖了TS相关包：如果组件包的package.json里把typescript、@types/react等TS依赖放在了dependencies而非devDependencies，这些依赖会被安装到你的项目中，导致create-react-app检测到TS环境。把这类依赖移到devDependencies，确保构建时不将它们打包进组件包产物。
create-react-app的隐式TS触发：create-react-app会根据项目中存在的TS相关文件（包括node_modules里的）自动启用TS编译逻辑。可以在你的项目根目录创建jsconfig.json，明确声明这是JS项目：
```
{
  "compilerOptions": {
    "module": "ESNext",
    "target": "ES6",
    "jsx": "react-jsx"
  },
  "include": ["src/**/*"]
}
```
组件包构建产物残留TS语法：比如构建时没把TS/TSX文件转译为纯JS/JSX，导致产物里有TS语法。检查组件包的构建脚本，确保用Babel或TSC把代码转译为兼容的JS代码，输出.js/.jsx文件。
缓存干扰：create-react-app的缓存可能保留了旧的TS相关配置。删除node_modules、package-lock.json（或yarn.lock），重新安装依赖后重启开发服务。