莫娜占卜铺技术排障手册：从环境搭建到数据处理的避坑指南

前言

莫娜占卜铺（genshin_artifact）是一个专注于《原神》游戏中的圣遗物搭配与分析的开源项目。该项目提供了多方向的圣遗物自动搭配、潜力与评分功能，帮助玩家优化角色装备。本手册将围绕环境配置、依赖管理和数据处理三个核心维度，为您提供阶梯式的问题解决方案，助您顺利运行项目。

一、环境配置类问题

1.1 Rust工具链配置异常

适用场景：首次克隆项目后执行编译命令，或系统中从未安装过Rust环境时。

难度指数：★★☆☆☆
解决时间预估：15-25分钟

预判排查

当您运行npm run build:wasm命令后，终端出现类似"rustc: command not found"或"cargo: command not found"的错误提示，基本可以判断为Rust工具链未正确安装。

核心解决

1. 安装Rust工具链

   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
   

   此命令会下载并安装Rust官方工具链，包括rustc（Rust编译器）、cargo（Rust包管理器）等核心组件。

2. 配置环境变量

   source $HOME/.cargo/env
   

   使Rust相关命令在当前终端会话中生效。

3. 安装WebAssembly工具链

   cargo install wasm-pack
   

   WebAssembly工具链 - 用于将Rust代码编译为浏览器可执行模块。

4. 验证安装

   rustc --version && cargo --version && wasm-pack --version
   

   确认三个命令都能正常输出版本信息。

替代方案

如果官方安装脚本因网络问题无法访问，可尝试国内镜像：

RUSTUP_DIST_SERVER=https://mirrors.ustc.edu.cn/rust-static rustup-init

预防措施

• 在项目README中添加Rust版本要求（建议1.56.0以上）
• 将$HOME/.cargo/bin添加到系统环境变量配置文件（如~/.bashrc或~/.zshrc）

常见误区：新手常忽略环境变量配置步骤，导致安装后仍无法使用cargo命令。请确保执行source $HOME/.cargo/env或重启终端。

1.2 Node.js环境版本不兼容

适用场景：执行npm install时出现大量依赖安装错误，或运行npm run dev时出现语法错误。

难度指数：★☆☆☆☆
解决时间预估：10-15分钟

预判排查

运行node -v查看当前Node.js版本，与项目package.json中engines字段要求对比，若版本差距较大则可能存在兼容性问题。

核心解决

1. 安装nvm（Node版本管理器）

   curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash
   

2. 安装推荐版本Node.js

   nvm install 16.14.2  # 示例版本，具体以项目要求为准
   nvm use 16.14.2
   

3. 验证Node.js和npm版本

   node -v && npm -v
   

替代方案

如果无法安装nvm，可直接从Node.js官网下载LTS版本安装。

预防措施

• 在项目根目录添加.nvmrc文件，指定推荐Node.js版本
• 定期更新package.json中的依赖版本，保持与最新LTS版本兼容

常见误区：使用过高版本的Node.js可能导致依赖不兼容。建议严格按照项目要求的版本安装，而非盲目追求最新版。

二、依赖管理类问题

2.1 npm依赖安装失败

适用场景：执行npm install命令时，出现依赖下载超时或编译失败。

难度指数：★★☆☆☆
解决时间预估：15-30分钟

预判排查

查看终端输出的错误信息，若出现"ETIMEDOUT"或"404 Not Found"等网络相关错误，可能是网络问题；若出现node-gyp相关错误，则可能是缺少编译工具。

核心解决

1. 清理npm缓存

   npm cache clean --force
   

2. 设置国内镜像源

   npm config set registry https://registry.npmmirror.com
   

3. 安装依赖

   npm install
   

替代方案

如果npm仍无法正常工作，可尝试使用yarn：

npm install -g yarn
yarn install

预防措施

• 在项目根目录添加.npmrc文件，预设国内镜像源
• 定期更新package.json中的依赖版本，修复已知安全漏洞

常见误区：频繁切换镜像源可能导致依赖版本不一致。建议设置一个稳定的镜像源，并坚持使用。

2.2 Rust依赖编译失败

适用场景：执行cargo build或npm run build:wasm时，出现Rust依赖编译错误。

难度指数：★★★☆☆
解决时间预估：20-40分钟

预判排查

查看终端输出的错误信息，注意寻找"error: "开头的行，通常会指示具体哪个依赖包编译失败。

核心解决

1. 更新Rust工具链

   rustup update
   

2. 清理cargo缓存

   cargo clean
   

3. 重新编译

   cargo build
   

替代方案

如果特定依赖包持续编译失败，可尝试手动指定版本： 在Cargo.toml中找到对应依赖，指定一个已知兼容的版本号。

预防措施

• 定期更新Cargo.lock文件，保持依赖版本稳定
• 在README中记录已知兼容的依赖版本组合

常见误区：忽视Cargo.lock文件的作用，频繁更新依赖版本。建议在项目稳定后锁定依赖版本，避免意外的兼容性问题。

三、数据处理类问题

3.1 数据文件生成失败

适用场景：执行npm run gen_meta命令后，目标目录下未生成预期的数据文件。

难度指数：★★★☆☆
解决时间预估：25-45分钟

预判排查

检查终端输出日志，寻找"Error"或"Panic"等关键词，同时确认mona_generate目录下是否存在output文件夹。

核心解决

1. 检查Rust环境

   cargo --version
   

   确保Rust环境正常。

2. 手动运行生成工具

   cd mona_generate
   cargo run --release
   

   直接运行生成工具，观察详细输出。

3. 检查模板文件

   ls templates/
   

   确保模板文件存在且格式正确。

替代方案

如果自动生成持续失败，可从项目仓库下载预生成的数据文件：

# 假设项目仓库中有预生成数据分支
git checkout data-files
cp mona_generate/output/* ../src/assets/

预防措施

• 添加数据文件生成检查脚本，在CI/CD流程中自动验证
• 提供预生成数据文件的下载选项，作为备选方案

常见误区：生成数据文件前未编译Rust代码。请确保先执行npm run build:wasm，再执行npm run gen_meta。

3.2 圣遗物数据分析异常

适用场景：使用圣遗物分析功能时，界面显示数据异常或报错。

难度指数：★★★★☆
解决时间预估：30-60分钟

预判排查

打开浏览器开发者工具（F12），查看Console面板是否有JavaScript错误，同时检查Network面板中API请求是否成功。

核心解决

1. 清除浏览器缓存

   # 不同浏览器操作方式不同，通常可通过Ctrl+Shift+Del打开清除缓存界面
   

2. 重新生成数据文件

   npm run gen_meta
   

3. 检查数据文件完整性

   ls src/assets/ | grep -E "_gen_|.json"
   

   确保所有必要的数据文件都已生成。

替代方案

如果特定功能持续异常，可尝试使用项目的稳定版本：

git checkout v1.0.0  # 替换为最新的稳定版本号

预防措施

• 添加数据校验机制，在应用启动时检查数据文件完整性
• 实现数据文件版本控制，确保前后端数据版本匹配

常见误区：修改数据文件后未重新构建项目。数据文件变更后，需要重新执行npm run build才能生效。

问题自查流程图提示

建议在文章结尾处添加问题自查流程图，帮助用户快速定位问题类型：

1. 问题发生在哪个阶段？（环境搭建/依赖安装/数据生成/功能使用）
2. 错误提示中是否有关键词？（rustc/cargo/npm/wasm/gen_meta）
3. 尝试过哪些解决方案？效果如何？

通过以上问题的回答，可快速缩小问题范围，提高解决效率。