前端项目启动失败主因是node-sass编译失败、peerDependencies冲突及模块缺失；应优先换用sass，或按Node版本匹配node-sass，用--legacy-peer-deps绕过依赖检查，再清缓存重装。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
你想让别人写好的前端项目在本地跑起来，却卡在 npm install 报错、node-sass 编译失败、模块找不到这些依赖问题上，根本进不了开发环节。
先确认是否满足启动前提
打开终端，执行 node --version 和 npm --version，确保 Node.js 版本落在项目要求范围内——常见 Vue 3 + Vite 项目需 Node 18.17+，React 18 + Webpack 5 项目多要求 Node 16.14–18.20。若版本不匹配，【AionClaw 启动技能会自动调用 nvm 切换，但前提是你的系统已安装 nvm 且配置正确】。
检查项目根目录是否存在完整 package.json 和 node_modules 文件夹。如果 node_modules 是空的或明显缺失（比如只有 .bin 目录），说明依赖尚未安装或中途失败。
不要把项目放在微信/QQ临时下载目录、iCloud/OneDrive 同步中未完成的文件夹里——AionClaw 扫描时会跳过这些路径，导致识别失败。
立即学习“前端免费学习笔记（深入）”；
快速修复三类高频依赖错误
方法一：node-sass 编译失败（gyp ERR!）
直接卸载 node-sass 并替换为纯 JS 实现的 sass：npm uninstall node-sass && npm install sass --save-dev。这一步操作起来很简单，90% 的老项目都能立刻解决编译报错。
若必须保留 node-sass（如 legacy Vue2 + Webpack4 项目），请严格对照版本表切换 Node 版本：Node 16.x → node-sass@6.0.x；Node 18.x → node-sass@8.0.x+。用 nvm use 16.14.2 这类命令切换后，再删 node_modules + package-lock.json 重装。
方法二：peerDependencies 冲突（npm ERR! peer vue@"^3.0.0"）
老项目直接加参数绕过检查：npm install --legacy-peer-deps。新项目谨慎使用 npm install --force，它可能覆盖关键依赖引发后续运行时错误。
方法三：Cannot find module 'xxx'（如 webpack-cli/bin/config-yargs）
先判断缺失的是 CLI 工具还是运行时依赖。如果是 webpack-cli、vue-cli-service 这类命令行工具，执行 npm install -D webpack-cli@latest 补全；如果是 vue-template-compiler 这类构建依赖，注意它必须与 vue 版本严格一致——Vue 3 项目不需要它，装了反而报错。
执行 AionClaw 一键修复流程
第一步：打开 AionClaw 客户端 → 左侧导航点击【自动化 (RPA)】→ 顶部搜索栏输入“前端项目启动”
第二步：点击运行【一键启动已有前端项目】技能 → 在弹出窗口中选择你已确认满足前提条件的项目文件夹
第三步：技能自动执行：读取 package.json → 检测 Node 版本 → 若不匹配则调用 nvm 切换 → 删除损坏的 node_modules → 静默执行 npm install（自动启用 --legacy-peer-deps 策略）→ 启动 dev server
整个过程无弹窗、不中断，控制台输出绿色 success 日志即表示依赖已就位，浏览器将自动打开 http://localhost:3000 或对应端口。
