前端编译错误修复：几招搞定 webpack/vite 报错不跑路

写完一行代码，保存，浏览器一刷新——白屏、控制台红字、终端里一堆英文报错。别慌，这可能是前端项目最常见的‘编译错误’，不是你代码写错了，而是构建工具卡在了某一步。

先看报错在哪，别瞎删 node_modules

打开终端，找最顶上那行带 Error: 或 Failed to compile 的提示。重点盯三处：文件路径（比如 src/components/Header.jsx:12）、错误类型（比如 Unexpected token '}'、Module not found）、错误行号。这些比后面一长串堆栈有用得多。

常见错误 & 快速解法

1. JSX 语法写漏了括号或引号
比如把：

<img src={avatarUrl} alt=用户头像 />

写成：

<img src={avatarUrl} alt=用户头像 />

（alt 值没加引号）——Vite 会直接报 Unexpected token。改成 alt="用户头像" 就过。

2. 引入的模块名拼错了，或路径不对
比如：

import { useModal } from '@/hooks/useMoadl';

手抖把 useModal 写成 useMoadl，webpack 就会报 Cannot find module '@/hooks/useMoadl'。检查拼写，再确认文件真实存在、大小写一致（Linux/macOS 下 UseModal.js 和 usemodal.js 是两个文件）。

3. CSS/SCSS 文件里用了未安装的预处理器
Vite 默认不支持 .scss。如果写了 import './index.scss'; 却没装 sass，终端就会报 Failed to resolve import './index.scss'。执行：

npm install sass --save-dev

就行，不用重启服务，改完保存自动重编译。

遇到 ‘Module parse failed’ 别硬扛

比如报错：

Module parse failed: Unexpected token (1:0)
You may need an appropriate loader to handle this file type.

大概率是你引入了一个非 JS/TS 文件（比如 JSON、SVG、MDX），但没配对应 loader。最简单粗暴的办法：用 require 替代 import 临时绕过，例如：

const data = require('./config.json');

或者，在 vite.config.ts 里加一句：

export default defineConfig({
  resolve: {
    alias: {
      '@data': path.resolve(__dirname, 'src/data')
    }
  }
});

让路径更可控。

最后提醒一句：改完代码后，别急着关终端。有些错误（比如 ESLint 配置崩了）会导致热更新失效，手动按 Ctrl+C 停掉服务，再 npm run dev 重新启一次，往往比对着报错干瞪眼快得多。