编译失败时应先查看控制台日志，错误信息基本都藏在里面；例如“cannot find module 'sass'”说明缺依赖，“uncaught referenceerror”表明插件未生效，“parsing error”多因vue模板语法错误，带路径的报错可直接定位到行。
编译失败时先看控制台日志
别急着删文件或重装，运行->运行到手机/浏览器后点开控制台，错误信息基本都藏在里面。很多问题其实就差一行提示：比如 Error: Cannot find module 'sass' 说明缺依赖，Uncaught ReferenceError: axios is not defined 是插件没生效，Parsing error: Unexpected token 多半是 Vue 模板写错了。日志里带路径的报错（如 xxx.vue:12:5）直接定位到行，比猜快得多。
SCSS/Sass 编译失败：插件 + 依赖双检查
HBuilderX 不自带 SCSS 编译能力，必须靠插件+本地依赖配合。光装插件不装 sass 包，或者只装 sass 不装插件，都会报错。
HBuilderX（Linux）
下载
HBuilderX 是由 DCloud 推出的一款轻量级前端开发工具，在 Linux 系统上主要用于 Web 开发与跨平台应用开发，尤其适合 Vue 和 uni-app 相关项目。
- 插件必须从 HBuilderX 内置插件市场安装，路径：
菜单栏->插件->插件安装->搜索“SCSS/Sass编译插件”，选官方出品 - 项目根目录下要存在
package.json，且含"sass": "^1.77.0"（或更高）和"sass-loader": "^14.2.1"（若用 webpack） - Windows 用户常见坑：
node-sass-china目录下win32-x64-72\binding.node版本不对——用node -p "[process.platform, process.arch, process.versions.modules].join('-')"确认版本号，再手动下载对应binding.node放进去
uni-app/Vue 编译失败：环境与语法强绑定
uni-app 的编译器和 Vue 版本、HBuilderX 版本三者必须对得上。HBuilderX 3.0+ 才完整支持 Vue 3 + setup 语法，旧版强行写 <script setup></script> 就会静默失败。
- 检查 HBuilderX 版本：
帮助->关于 HBuilderX，低于3.9.0建议升级（官网最新版已到4.12.0） - 确认项目类型：右键项目根目录 ->
配置为 uni-app 项目，否则 HBuilderX 当普通 HTML 处理，不触发 Vue 编译 -
<template></template>里写了小程序组件（如<uni-popup></uni-popup>）但运行目标选了 H5？会报Unknown custom element—— 切换运行环境再试
插件导入失败：结构比内容更重要
插件导入失败，90% 是因为目录结构被破坏。HBuilderX 要求 manifest.json 必须在压缩包最外层，不能套着 my-plugin-master/ 这种文件夹。
- 从 GitHub 下载的 zip 包，解压后如果看到一层同名文件夹，需把里面所有文件（含
manifest.json）剪切出来，重新打包成 zip - 插件根目录下必须有
main.js或manifest.json中指定的entry文件，缺一不可 - 导入后没反应？关掉 HBuilderX，删掉
plugins目录下同名文件夹，再重试——缓存有时会卡住识别
@esbuild/darwin-arm64 和 @esbuild/darwin-x64 混用）、以及 HBuilderX 自身构建流程的隐式依赖之间互相打架。查日志、锁版本、清缓存，这三步走完，80% 的编译失败都能当场解决。
