net::err_failed本质是本地路径或配置错误，90%因index.html加载了错误js/css路径，需检查项目根目录无中文/空格、manifest.json中publicpath设为"./"、network面板红标请求路径是否匹配实际文件位置。
net::ERR_FAILED 是路径或配置问题，不是网络故障
这个错误看起来像网络问题，实际几乎全是本地配置导致的。浏览器 Network 面板里标红的资源，90% 是 index.html 加载了错误路径的 js 或 css，比如请求了 /static/js/app.abc123.js 但实际文件在 ./static/js/app.abc123.js。
- 立刻检查项目根目录路径：不能含中文、空格、括号（如
C:\Users\张三\my-uni→ 改为C:\dev\my-uni） - 打开
manifest.json→ “H5 配置” → 确认publicPath设为"./"（不是"/"或空字符串） - 运行后打开浏览器开发者工具 → Network 标签页 → 刷新 → 找第一个红色请求 → 看它的 Request URL 和实际文件位置是否匹配
- 如果用 history 模式路由，确保服务器支持 fallback（HBuilderX 内置服务已处理，但自定义 Nginx 或部署时需额外配置）
failed to load config from vite.config.js 本质是 uni 插件没加载
报错里出现 TypeError: uni is not a function，说明 Vite 启动时找不到 uni 这个插件入口。这不是你写的代码问题，而是 HBuilderX 和项目环境没对齐。
- HBuilderX 版本必须 ≥ 3.9.8（Vue3 + UniApp 要求），旧版本直接不兼容
vite.config.js - 删掉
node_modules和package-lock.json，用 HBuilderX 自带终端执行npm install（不要用全局 npm） - 确认项目根目录有
vite.config.js，且第一行是import { defineConfig } from 'vite'，不是module.exports = {...} - 如果用的是 HBuilderX 4.86+，已知存在 TypeScript 类型服务异常，会导致配置解析失败；降级到 4.36 更稳
Module not found: Cannot find module '@ohos/xxx' 是鸿蒙模块未声明
真机调试鸿蒙应用时，编译器不会自动注入系统模块，哪怕你只调了一行 AccessibilityManager.setEnabled()，也得显式告诉它“我要用这个能力”。
- 在
src/main/manifest.json里补权限（如需要无障碍）：{"reqPermissions":[{"name":"ohos.permission.ACCESSIBILITY"}]} - 在
build-profile.json5的modules数组里加依赖："@ohos/ability/accessibility"、"@ohos/permission"等 - 改完必须重新点击“运行到鸿蒙”，不能只 Ctrl+S 后热更新——鸿蒙构建链路不支持增量注入模块
- 注意：鸿蒙模块名大小写敏感，
@ohos/ability/accessibility不能写成@OHOS/ability/accessibility
基座不包含插件 不是插件没放对，是没重打自定义基座
原生插件（比如扫码、蓝牙）必须打包进运行基座才能生效。“基座不包含插件”不是说插件没识别到，而是你还在用默认基座跑——默认基座根本不含任何第三方 native 代码。
- 插件必须放在
nativeplugins/xxx/下，且xxx/package.json中platforms字段要明确列出"app-plus" - manifest.json 的
app-plus → nativePlugins节点要完整填写插件名和 class 全路径 - 关键动作：菜单栏 → 运行 → 运行到手机或模拟器 → 弹窗里勾选“使用自定义基座” → 点击“制作自定义基座”（会触发完整 rebuild）
- 制作过程耗时较长，期间别关 HBuilderX；完成后重启 IDE 再运行，否则仍走旧基座缓存
最常被忽略的是：所有路径类问题（中文、空格、publicPath）和鸿蒙模块声明，这两类错误不会报语法错，而是静默失败或白屏。排查时优先看 Network 面板和真机日志输出，别只盯着控制台红字。
