Ubuntu 24.04 极简安装 MiroFish 教程|避开两大核心坑,一次成功不返工

昨晚刚给笔记本重装了Ubuntu 24.04 LTS，第一时间想把最近很火的 MiroFish 重新部署好。本以为是常规安装流程，结果踩了两个坑，折腾了快一个小时才搞定，索性把完整的极简安装步骤+踩坑解决方案整理出来，帮各位Ubuntu用户直接跳过雷区。

前置说明：本次安装采用压缩包手动部署方式，Ubuntu 24.04 LTS 系统自带基础环境，但自带版本存在兼容性问题，这也是踩坑的核心原因，提前给大家划重点！

一、系统自带环境（避坑预警）

Ubuntu 24.04 LTS 默认预装了运行相关依赖，但版本刚好卡在兼容边缘，千万别直接用自带版本硬跑，不然直接报错卡壳：

Node.js：自带18.x版本（Mirofish官方文档模糊标注≥18，实际运行要求更高，第一个大坑就在这）
Python：自带3.12.3版本，版本适配无问题，无需额外重装

二、极简完整安装命令（复制粘贴即可）

全程在终端执行，按照顺序一步步来，先把基础依赖装完，再执行MiroFish核心部署命令，注意核对每一步的执行反馈，不要跳过任意步骤。

# 第一步：安装基础工具curl，用于后续下载依赖sudo apt-get update && sudo apt-get install curl -y# 第二步：安装Python包管理工具UV# 注：安装后直接输uv --version会报错，第二个坑就在这，后面附解决方案curl -LsSf https://astral.sh/uv/install.sh | sh# 第三步：安装npm包管理工具sudo apt-get install npm -y# 第四步：进入MiroFish解压后的根目录，执行全局部署# 重点：首次安装依赖超多，耐心等待，网络正常情况下15-20分钟，切勿中断cd Mirofishnpm run setup:all

执行完 npm run setup:all 后，等待终端跑完所有依赖安装流程，没有报错的话基础部署就完成了，但大概率会遇到Node版本报错和UV命令找不到的问题，也就是下面要详解的两大核心坑。

三、两大致命坑+一站式解决方案（必看）

这两个坑是Ubuntu 24.04 安装MiroFish的专属雷区。直接上亲测有效的解决办法，一步到位修复。

坑1：Node.js 版本不兼容（官方文档误导，实际要求远高于18.x）

官方文档只写Node.js≥18即可，但实际执行 npm run dev 启动项目时，会直接报错提示：Node.js版本需≥20.19或≥22.12，自带的18.x完全无法运行，必须升级Node版本。

推荐用**nvm（Node版本管理工具）**升级，支持多版本切换，不会破坏系统原有环境，命令如下：

# 1. 安装nvm工具（未安装过的执行，已安装可跳过）curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash# 2. 立即生效nvm命令，无需重启终端export NVM_DIR="$HOME/.nvm"[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"# 3. 验证nvm是否安装成功，输出版本号即生效nvm --version# 4. 安装Node.js最新LTS长期支持版本（完美适配MiroFish）nvm install --lts# 5. 切换到刚安装的LTS版本nvm use --lts# 6. 验证Node版本，确认≥20.19即修复完成node -v

坑2：UV安装后命令找不到（uv: command not found）

执行UV安装脚本后，终端输入 uv --version 提示命令不存在，这是最常见的环境变量问题，不是安装失败，无需卸载重装，只需手动配置系统路径即可永久解决。

原因：UV默认安装到 ~/.local/bin 目录，系统Shell没有读取到这个路径，添加环境变量后即可识别。

# 1. 临时生效UV路径（当前终端立即可用）export PATH="$HOME/.local/bin:$PATH"# 2. 永久配置环境变量，重启终端后依然生效echo'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc# 3. 刷新配置，立即生效永久配置source ~/.bashrc# 4. 验证UV是否可用，输出版本号即修复成功uv --version

四、安装完成后验证步骤

修复完两个坑后，回到MiroFish根目录，重新执行启动命令，正常运行无报错即安装成功：

# 进入项目根目录cd Mirofish# 启动MiroFishnpm run dev

最终检查：终端无报错、正常输出启动日志，且能通过浏览器访问对应地址，就是安装成功啦～

五、额外小贴士

如果执行命令时提示权限不足，全程加 sudo 即可，Ubuntu环境下部署工具类项目，建议赋予足够权限
首次 npm run setup:all 超时或中断，直接删除node_modules文件夹，重新执行命令即可
Ubuntu其他版本可参考本教程，Node版本问题同样适用

以上就是Ubuntu 24.04 安装MiroFish的全流程，核心就是避开Node版本和UV环境变量这两个坑，照着步骤来基本不会出问题。如果大家还有其他踩坑点，欢迎留言交流～