React+TypeScript+Webpack项目执行npm run dev报错求助

从报错截图来看，问题集中在TypeScript类型校验与webpack编译环节，结合你已尝试的排查动作，给出以下针对性解决步骤：

1. 对齐本地与项目的TypeScript版本 #

全局TS版本和项目依赖的TS版本冲突是常见诱因，先确认版本差异：

• 查看全局TS版本：tsc -v
• 查看项目本地TS版本：npm list typescript

如果版本不一致，卸载全局TS，强制使用项目本地版本：

npm uninstall -g typescript
# 验证是否切换为本地版本
npx tsc -v

2. 补全缺失的@types类型声明包 #

多数TS编译错误源于缺少对应库的类型声明，执行以下命令安装核心依赖的类型包：

npm install @types/react @types/react-dom --save-dev

若项目使用其他第三方库（如lodash、axios等），需同步安装对应的@types/xxx包。

3. 检查并修复tsconfig.json配置 #

tsconfig.json的错误配置会直接导致TS编译失败，重点检查以下字段：

• compilerOptions.target与module需和webpack输出配置匹配（推荐ESNext或ES6）
• jsx字段设置为react-jsx（React 17+版本适配）
• include需覆盖项目源码目录（如["src/**/*"]），exclude排除node_modules和构建目录

参考标准配置示例：

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "jsx": "react-jsx",
    "strict": true,
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "build"]
}

4. 清理webpack缓存 #

webpack缓存可能残留旧编译信息，导致错误重复出现，执行以下命令清理：

# 清理webpack5内置缓存
rm -rf node_modules/.cache
# 若项目使用cache-loader，需删除对应缓存目录（通常在node_modules下或项目根目录的.cache文件夹）

清理后重新执行npm run dev。

5. 对齐Node.js版本与同事一致 #

Node.js版本差异可能导致依赖安装或编译逻辑异常，用nvm快速切换版本：

# 安装nvm（未安装时执行）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
# 切换到同事使用的Node.js版本（示例为v18.17.0）
nvm install 18.17.0
nvm use 18.17.0

切换后删除node_modules、package-lock.json，重新执行npm i。

6. 验证webpack的TS文件处理配置 #

确保webpack配置中正确配置了TS/TSX文件的加载器（ts-loader或babel-loader）：
示例webpack.dev.js配置片段：

module.exports = {
  module: {
    rules: [
      {
        test: /\.(ts|tsx)$/,
        exclude: /node_modules/,
        loader: 'ts-loader',
        options: {
          transpileOnly: true // 开发环境可开启，提升编译速度
        }
      }
    ]
  },
  resolve: {
    extensions: ['.ts', '.tsx', '.js', '.jsx'] // 确保webpack能识别TS后缀
  }
}

若使用babel-loader，需确保@babel/preset-typescript已安装并加入babel配置。

内容的提问来源于stack exchange，提问作者NMJ