安装、更新、卸载与排查。

macOS 安装

1. 完全退出 Illustrator。
2. 双击下载的 HopeFlow-Toolbox-3.2.12-macOS-secure.dmg 打开。
3. 双击里面的「HopeFlow 安装器」。首次打开若提示来自身份不明的开发者，请在它上面点右键 → 打开。
4. 安装器标题为「正在为您的 Illustrator 安装 HopeFlow」，会自动检测已安装的版本并显示进度。较慢的一步会显示「正在准备 AI 环境...」，完成后点「完成」。
5. 重新启动 Illustrator。

也可使用 ZIP 版 HopeFlow-Toolbox-3.2.12-macOS-secure.zip：解压后打开「HopeFlow 安装器.app」，装出来的内容与 DMG 一致。

Windows 安装

1. 完全退出 Illustrator。
2. 双击 HopeFlow-Toolbox-3.2.12-Windows-secure-Installer.exe。若出现「Windows 已保护你的电脑」，点「更多信息 → 仍要运行」。
3. 安装器窗口标题为「HopeFlow 安装器」，会自动检测已安装的 Illustrator 并显示进度。较慢的一步会显示「正在准备 AI 环境...」，完成后点「完成」。
4. 重新启动 Illustrator。

如果安装器被杀毒软件直接删除或拦下，请改用下载页的 ZIP 版 HopeFlow-Toolbox-3.2.12-Windows-secure.zip：解压后双击 HopeFlow-Installer.bat，装出来的内容与 .exe 完全一致。

在 Illustrator 中打开

进入「窗口 → 扩展功能 → HopeFlow 工具箱」。面板支持跟随 Illustrator 主题，并可配置主色。

更新与重装

从旧版本升到 v3.2.12，或同一版本重装，都用同一套安装器。不必先卸载。

能不能直接覆盖安装

可以。再运行一次新版安装器即可覆盖旧文件。安装器会先写到临时目录，成功后再替换现有面板；这一步失败时会把旧目录换回来，避免留下半残安装。

更新前要关闭 Illustrator

必须完全退出 Illustrator（不是只关文档或关掉面板）。Windows 安装器会先结束后台引擎；若仍提示文件被占用，请在任务管理器里确认 Illustrator 已退出后再装。

更新后要重启 Illustrator

安装器完成页会提示：重启 Illustrator，从「窗口 → 扩展功能」打开 HopeFlow 工具箱。不重启时，面板可能仍是旧版本，或原生组件未加载。

设置、授权和 AI 环境会保留

会保留。覆盖安装只替换插件目录和 HopeFlow.aip，不会删除用户主目录下的 .hopeflow。这里存放本机设置、授权信息和独立 Python 环境，重装后不必重新登录或重新准备 AI 环境。

更新失败后怎么恢复

1. 完全退出 Illustrator，再运行一次同一份安装器。
2. 若 Windows 提示无法删除旧版本目录，先结束后台 Illustrator 进程，再重试。
3. 若进度停在「正在准备 AI 环境...」或显示「AI 环境未装成（不影响面板使用）」，面板和增效工具已经装好。稍后按 Python 环境 一节修复即可，不必整包重来。
4. 仍失败时，用 ZIP 版做一次标准卸载（见下一节），再重新安装。只要没有删除 .hopeflow，设置和授权都在。
5. 把安装器里的「复制日志」发给我们。macOS 日志还在 ~/Library/Logs/HopeFlow-Installer.log。

卸载 HopeFlow

卸载前请完全退出 Illustrator。卸载面板时还要删除随插件安装的 HopeFlow.aip，否则 Illustrator 中仍可能残留 HopeFlow 的原生功能。

.\HopeFlow-Installer.bat -Uninstall

./install.sh --uninstall

标准卸载与彻底清理

以上标准卸载会保留 HopeFlow 的设置、授权信息和 AI 运行环境，方便以后重装。若要连同个人数据一起清除，再删除用户主目录下的 .hopeflow 文件夹：

• Windows：%USERPROFILE%\.hopeflow
• macOS：~/.hopeflow

此操作会清除本机设置、授权缓存、更新缓存和已下载的 AI 运行环境。完成后重新启动 Illustrator，确认「窗口 → 扩展功能」中已没有 HopeFlow 工具箱。

Python 环境

安装器会自动准备一套 HopeFlow 独立 Python 环境。进度条上对应的文字是「正在准备 AI 环境...」。它装在你的用户目录里，不需要管理员权限，也不会修改系统 Python（不论官方安装、Homebrew、conda 还是 Microsoft Store 占位程序）。

谁需要它

CEP 面板和大多数工具不依赖 Python。需要本地引擎的功能包括：AI 绘图、大尺寸导出、透视校正，以及数据合并导出 PDF、专色 TIFF / PDF。这些计算都在本机完成（AI 绘图会访问你自己配置的在线接口）。

装在哪里

• Windows：C:\Users\<你的用户名>\.hopeflow\python\
• macOS：/Users/<你的用户名>/.hopeflow/python/

当前 v3.2.12 准备的是 Python 3.12，具体目录名为 3.12.13。不写入系统 PATH，不改注册表，不开机自启。

下载失败

这一步需要联网：先下载独立运行时，再安装依赖。安装器可能依次显示「正在下载 Python 运行时...」「正在校验文件完整性...」「正在安装 AI 依赖（较慢，请耐心等待）...」。

• 换一个网络重试，手机热点常常比公司网络更通。
• 若提示校验失败，安装会直接中止，不会写入半残文件。换网络后再跑一次。
• Python 没装成时，安装器会显示「AI 环境未装成（不影响面板使用）」。面板和增效工具已经可用，只是上述依赖 Python 的功能暂时不能用。

依赖失败

脚本会依次尝试清华、阿里云和官方 PyPI。全部失败时，把日志发给我们即可。重跑是安全的，已下载的部分不会白费。

• macOS：~/.hopeflow/python-setup.log
• Windows：C:\Users\<用户名>\.hopeflow\python-setup.log

重新安装自带环境

1. 打开面板，进入设置里的「Python 环境」（说明文字为「统一使用自带运行时」）。
2. 确认当前状态后，点「安装 / 修复自带环境」。装好后应显示「运行环境已就绪」。
3. 也可点「重新检查」只查看状态，不重新下载。

也可以手动跑安装目录里的脚本（与安装器、面板用的是同一份）：

• macOS：~/Library/Application Support/Adobe/CEP/extensions/com.hopeflow.toolbox/tools/python-setup/setup-python.sh
• Windows：在 %APPDATA%\Adobe\CEP\extensions\com.hopeflow.toolbox\tools\python-setup\ 中运行 setup-python.ps1。若禁止运行脚本，使用 powershell -ExecutionPolicy Bypass -File .\setup-python.ps1。

已经装坏时加上 --force（Windows 为 -Force）强制重装。装好后请完全退出并重新打开 Illustrator。

备用：使用本机已有的 Python

当前 v3.2.12 面板只使用 HopeFlow 自带运行时，不再扫描 Homebrew、conda、py 启动器或系统 PATH，以免再次选中系统保护的解释器。若必须改用本机已有的 Python 3.9–3.12，请先确认自带环境无法修复，再通过公众号把解释器路径发给我们协助排查。安装器可用 --no-python（Windows 为 -NoPython）跳过自动准备，但 AI 相关功能仍要等独立环境就绪后才能用。

兼容性

「支持 Illustrator 2019–2026」指的是 CEP 面板，不是每一个原生功能。HopeFlow AIP 用 2021 SDK 编译，只安装到 Illustrator 2021–2026；2019 和 2020 可以打开面板、使用 JSX 功能，但不会加载原生组件。

常见问题