macOS 便携版 iFlow CLI 部署文档 (USB 随身版)

iFlow 补给站
1

文档版本: 1.0 适用系统: macOS (Intel & Apple Silicon) 最后更新: 2025-12-26

参考：把iflow装进U盘，随插随用 写了一个macos版本的

1、项目简介

本项目旨在创建一个基于 USB 存储设备的 iFlow CLI 便携运行环境。通过将 Node.js 运行时和 iFlow 依赖包完全封装在 U 盘中，实现“即插即用”，无需在宿主 Mac 电脑上安装任何环境，且不污染宿主机的系统环境。

2、核心原理

运行时隔离：使用 Node.js 的二进制包（Binary），通过 Shell 脚本动态修改 PATH 和 NODE_PATH 环境变量，强制指向 U 盘内的路径。

构建与运行分离：

  • 构建阶段 (Install)：负责下载依赖、配置目录，仅执行一次。

  • 运行阶段 (Start)：负责挂载环境、启动程序，日常使用。

3、目录结构规范

为了确保脚本正常运行，U 盘的文件结构必须严格遵守以下规范：

/Volumes/[U盘名称]/
├── install_iflow_mac.sh          # [构建脚本] 用于初次安装 (只运行一次)
└── PortableApps/
    ├── nodejs/
    │   └── node-macos/           # [核心环境] Node.js 解压目录 (需手动重命名)
    │       ├── bin/
    │       └── ...
    └── iflow/
        ├── node_modules/         # [依赖库] 脚本自动下载生成的目录
        └── start_iflow.sh        # [启动脚本] 日常使用入口 (安装后自动生成)

4、部署流程（一次型构建）

4.1 准备环境

1、下载 Node.js (推荐 v20 LTS 版本):

M1/M2/M3 (Apple Silicon): 下载 ARM64 版 .tar.gz

Intel Mac: 下载 x64 版 .tar.gz

2、解压与放置:

在 U 盘创建 /PortableApps/nodejs/ 目录。

将下载的压缩包解压，并将文件夹重命名为 node-macos。

确保路径正确：/PortableApps/nodejs/node-macos/bin/node 应当存在。

4.2 创建构建脚本

在 U 盘根目录创建文件 install_iflow_mac.sh，内容如下：

#!/bin/bash

echo "========================================"
echo "iFlow CLI 便携版自动安装脚本 (macOS)"
echo "========================================"
echo ""

# 获取脚本当前所在的目录 (假设脚本在U盘根目录或 PortableApps 同级)
# 如果脚本在 U盘/PortableApps/iflow 下，需调整层级。
# 这里假设脚本放在 U 盘根目录
SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
USB_ROOT="$SCRIPT_DIR"

echo "当前工作目录: $USB_ROOT"

# 定义目录结构
PORTABLE_DIR="$USB_ROOT/PortableApps"
NODE_DIR="$PORTABLE_DIR/nodejs/node-macos"
IFLOW_DIR="$PORTABLE_DIR/iflow"

# 检查 Node.js 是否存在
if [ ! -f "$NODE_DIR/bin/node" ]; then
    echo ""
    echo "错误：未找到 Node.js 二进制文件！"
    echo "请确保你已下载 Node.js macOS 版本并解压到以下位置："
    echo "$NODE_DIR"
    echo "注意：文件夹名称必须重命名为 'node-macos'"
    echo ""
    exit 1
fi

echo "找到 Node.js 目录: $NODE_DIR"

# 创建 iflow 目录
if [ ! -d "$IFLOW_DIR" ]; then
    mkdir -p "$IFLOW_DIR"
fi

# 设置临时环境变量以进行安装
export PATH="$NODE_DIR/bin:$PATH"
export NPM_CONFIG_PREFIX="$NODE_DIR"
# 确保 npm 全局安装目录存在
mkdir -p "$NODE_DIR/lib/node_modules"

echo "正在安装 iFlow CLI..."
echo "这可能需要几分钟，取决于你的 U 盘读写速度..."

# 安装 iFlow CLI
npm install -g @iflow-ai/iflow-cli

if [ $? -eq 0 ]; then
    echo "iFlow CLI 安装成功！"
else
    echo "安装失败，请检查网络或权限。"
    exit 1
fi

# 创建启动脚本 start_iflow.sh
START_SCRIPT="$IFLOW_DIR/start_iflow.sh"

echo "正在创建启动脚本..."

cat > "$START_SCRIPT" << 'EOF'
#!/bin/bash

# 获取脚本所在目录 (即 [U盘]/PortableApps/iflow)
SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
# 定位到 Node.js 目录 (向上两级找到 nodejs)
NODE_HOME="$SCRIPT_DIR/../../PortableApps/nodejs/node-macos"

# 设置环境变量
export PATH="$NODE_HOME/bin:$PATH"
export NODE_PATH="$NODE_HOME/lib/node_modules"
export NPM_CONFIG_PREFIX="$NODE_HOME"

echo "========================================"
echo "正在启动 iFlow CLI (Portable)..."
echo "========================================"

# 检查是否因 macOS Gatekeeper 导致权限问题
if [ ! -x "$NODE_HOME/bin/node" ]; then
    echo "正在尝试修复执行权限..."
    chmod +x "$NODE_HOME/bin/node"
    chmod +x "$NODE_HOME/bin/npm"
    chmod +x "$NODE_HOME/bin/iflow"
fi

# 启动 iflow
"$NODE_HOME/bin/iflow" "$@"

echo ""
echo "iFlow 已退出。"
# 保持窗口不立即关闭，方便查看报错
read -p "按回车键关闭..."
EOF

# 赋予启动脚本执行权限
chmod +x "$START_SCRIPT"

echo ""
echo "========================================"
echo "安装完成！"
echo "========================================"
echo "使用方法："
echo "1. 此时你可以将 '$START_SCRIPT' 拖动到终端中运行。"
echo "2. 或者创建一个 Alias 别名指向该脚本。"
echo ""

4.3 执行构建

打开终端，运行构建脚本：

chmod +x /Volumes/[U盘名]/install_iflow_mac.sh
/Volumes/[U盘名]/install_iflow_mac.sh

看到 “正在下载…” 时请耐心等待，不要按 Ctrl+C。直到出现 “:white_check_mark: 构建完成！” 字样。

5. 使用指南 (日常操作)

构建完成后，您在任何 Mac 上只需进行以下操作：

方式 A：拖拽运行 (最简单)

插入 U 盘。

打开终端。

将文件 /PortableApps/iflow/start_iflow.sh 拖入终端窗口。

按回车键即可启动。

方式 B：设置别名 (推荐)

如果您经常使用，可以在宿主机的 ~/.zshrc 中添加别名（注意路径需根据实际 U 盘名修改）：

alias iflow="/Volumes/WDW_S02OR42/PortableApps/iflow/start_iflow.sh"

之后只需在终端输入 iflow 即可。

6. 故障排查 (Troubleshooting)

Q1: 提示 “无法打开 node，因为无法验证开发者”
原因: macOS 的安全机制 (Gatekeeper) 拦截了 U 盘里的可执行文件。 解决: 在终端运行以下命令（移除隔离属性）：

sudo xattr -cr /Volumes/[U盘名]/PortableApps/nodejs/node-macos

Q2: 报错 “exec format error”
原因: 芯片架构不匹配。 解决:

如果您在 M1/M2/M3 芯片的 Mac 上使用，必须下载 ARM64 版本的 Node.js。

如果您在 Intel 芯片的 Mac 上使用，必须下载 x64 版本的 Node.js。

进阶方案: 如果需要同时兼容，可以下载两个版本的 Node.js 分别存放，并修改启动脚本进行架构判断 (uname -m)。

Q3: 运行速度慢

原因: U 盘的 4K 随机读写速度远低于 SSD。 建议: Node.js 项目包含大量小文件 (node_modules)，建议使用 USB 3.0 以上的高速 U 盘或移动固态硬盘 (PSSD)。

ocean-zhc's的知识库 > macOS 便携版 iFlow CLI 部署文档 (USB 随身版) > image-2025-12-26_11-30-27.png918×618 64.7 KB
ocean-zhc's的知识库 > macOS 便携版 iFlow CLI 部署文档 (USB 随身版) > image-2025-12-26_11-30-34.png1978×1100 189 KB

好了，快乐的玩耍吧，同理，可以把gemini，或者claude等node安装方式的，都可以举一反三装进U盘，但是需要有代理服务哟！

2

赞赞赞 :+1:

1 个赞
3

我还在想假期要不要带电脑，游戏本换成了超级本，现在带个U盘就好了，靓仔帅喔~

1 个赞