莫娜占卜铺技术难题突破指南：从入门到精通

莫娜占卜铺是专注于《原神》圣遗物搭配与分析的开源项目，提供多方向圣遗物自动搭配、潜力评估与评分功能。

诊断编译环境配置故障

问题场景：首次克隆项目后执行npm run build时，终端显示"rustc: command not found"或WASM编译失败。

阶梯式解决方案

🔧 初级处理（Windows/macOS/Linux通用）

1. 安装Rust工具链核心组件
2. 添加WebAssembly编译目标
3. 验证工具链完整性

🔧 进阶处理（针对复杂环境）

1. 检查Rustup镜像源配置
2. 清理旧工具链残留文件
3. 手动指定WASM编译路径

📌 预防措施

• 定期执行rustup update保持工具链最新
• 使用cargo --version和wasm-pack --version验证环境
• 避免在系统路径含中文或特殊字符的目录下编译

解决依赖安装冲突

问题场景：执行npm install时出现"node-gyp rebuild"失败或依赖版本不兼容警告。

阶梯式解决方案

🔧 初级处理（Windows/macOS/Linux通用）

1. 清除npm缓存数据
2. 强制重新安装依赖包
3. 检查Node.js版本兼容性

🔧 进阶处理（网络受限环境）

1. 配置npm镜像源
2. 手动安装指定版本依赖
3. 使用yarn替代npm管理依赖

📌 预防措施

• 保持Node.js版本在14.x以上LTS版本
• 定期更新package.json依赖版本
• 使用npm ls <package>检查依赖树冲突

修复数据文件生成失败

问题场景：运行npm run gen_meta后，output目录未生成_gen_character.js等核心数据文件。

阶梯式解决方案

🔧 初级处理（Windows/macOS/Linux通用）

1. 确认Rust编译环境正常
2. 检查模板文件完整性
3. 重新执行元数据生成命令

🔧 进阶处理（定制化需求）

1. 手动触发特定模块生成
2. 检查模板引擎配置
3. 验证数据文件输出权限

📌 预防措施

• 生成前确保templates目录存在
• 定期同步最新的游戏数据
• 备份已生成的核心数据文件

问题自检流程图

开始 → 克隆项目 → 安装Rust工具链? → 否 → 安装Rust → 是
→ 安装Node.js依赖? → 否 → 执行npm install → 是
→ 生成数据文件? → 否 → 执行npm run gen_meta → 是
→ 编译WASM模块? → 否 → 执行npm run build:wasm → 是
→ 启动应用 → 完成

社区支持渠道

1. 项目Issue跟踪：通过项目仓库提交详细错误报告
2. 开发者论坛：参与项目讨论区技术交流
3. 贡献者文档：查阅docs目录下的开发者指南

常见问题速查表

问题现象	可能原因	快速解决方案
编译提示"linker not found"	缺少系统编译工具	安装build-essential(Linux)或Xcode Command Line Tools(macOS)
npm安装卡住	网络连接问题	切换国内npm镜像
WASM加载失败	浏览器安全限制	使用localhost环境测试
数据文件缺失	生成步骤遗漏	执行npm run gen_meta
界面显示异常	前端资源未编译	执行npm run build