Webpack Module Not Found — resolve 扩展名或别名缺失

症状

遇到“Webpack Module Not Found — resolve 扩展名或别名缺失”时靠猜测只会浪费时间。请按证据排查：先复现症状，再执行针对性诊断，定位根因后修复，并用明确检查验证结果。

可观察到的症状包括：

• Module not found: Can’t resolve ‘./Button’ in /src
• 本地可用，在大小写敏感的 Linux 构建失败
• 看似绝对的导入无别名时失败

诊断

先在隔离环境中复现故障，再按顺序执行以下检查，逐步缩小范围。

步骤 1

npx webpack --stats-error-details 2>&1 | grep -A 5 "Can't resolve"

错误会显示发起文件与请求，揭示缺失的扩展名或别名。

步骤 2

grep -n "extensions\|alias" webpack.config.js tsconfig.json

确认已配置的扩展名与别名即可看出应补充什么。

常见诱因（按出现频率排序）：

• 导入省略了 webpack 默认不解析的扩展名（如 .tsx）
• 使用 @/ 等别名却未配置 resolve.alias
• 路径大小写与文件不同，本地文件系统不敏感而掩盖问题

根因

webpack 依据 resolve.extensions（默认 .js、.json、.wasm）与别名解析导入。无可用扩展名或别名的导入会失败；大小写不匹配在本地不敏感文件系统通过，却在 Linux 构建机上失败。

修复

把所需扩展名加入 resolve.extensions，为路径快捷方式定义别名，并精确匹配文件大小写，使构建可移植到大小写敏感文件系统。

注意：过宽的扩展名列表会拖慢解析；应保持有序且精简。

// webpack.config.js
module.exports = {
  resolve: {
    extensions: ['.ts', '.tsx', '.js', '.jsx', '.json'],
    alias: {
      '@': path.resolve(__dirname, 'src'),
    },
  },
};

// now both resolve
import Button from '@/components/Button';

验证

重新构建并确认模块解析成功；在大小写敏感环境中构建以捕获大小写不匹配。

修复后补充一条回归测试，复现原始症状，防止问题再次出现。

这类故障通常是环境问题而非纯逻辑错误，因此在缺陷记录中应写明完整命令、环境变量与工作目录。请用最小的脚本复现，待最小用例清楚后再扩大范围。为这类故障准备一份简短的排查清单，能显著减少下次排障时间。