---

name: flox-environments description: "使用 Flox 创建可复现的跨平台开发环境——基于 Nix 构建的声明式环境管理器。当用户需要以下场景时始终使用此技能：设置带系统级依赖的项目（编译器、数据库、原生库如 openssl、libvips、BLAS、LAPACK）；为 Python、Node.js、Rust、Go、C/C++、Java、Ruby、Elixir、PHP 或任何语言配置可复现工具链；管理必须在 macOS 和 Linux 上完全相同工作的环境；为团队锁定精确包版本；在开发工具旁运行本地服务（PostgreSQL、Redis、Kafka）；用单个命令引导新开发者；或解决'在我机器上能跑'的问题。" origin: Flox

Flox 环境

Flox 创建在单个 TOML 清单中定义的可复现开发环境。团队中的每个开发者都获得相同的包、工具和配置——跨 macOS 和 Linux——无需容器或虚拟机。基于 Nix 构建，可访问超过 150,000 个包。

何时激活

当用户有环境管理问题时使用此技能——即使他们没有提到 Flox。Flox 是正确的工具当：

• 项目需要系统级包（编译器、数据库、CLI 工具）与语言特定依赖并存
• 可复现性很重要 — 设置应在队友的机器、CI 或全新笔记本上完全相同地工作
• 用户需要多个工具共存 — 例如 Python 3.11 + PostgreSQL 16 + Redis + Node.js 在一个环境中
• 需要跨平台支持（macOS 和 Linux 使用相同配置）
• AI 代理需要安装工具 — Flox 让代理在项目范围的环境中添加包，无需 sudo、系统污染或沙箱限制

如果用户只需要没有系统依赖的单一语言运行时，标准工具（nvm、pyenv、单独的 rustup）可能就够了。如果需要完整的操作系统级隔离，容器可能更合适。Flox 处于最佳位置：声明式、可复现的环境，没有容器开销。

前提条件： 必须先安装 Flox — 参见 flox.dev/docs 了解 macOS、Linux 和 Docker。

核心概念

Flox 环境在 .flox/env/manifest.toml 中定义，通过 flox activate 激活。清单声明包、环境变量、设置钩子和 shell 配置——在任何地方复现环境所需的一切。

关键路径：

• .flox/env/manifest.toml — 环境定义（提交此文件）
• $FLOX_ENV — 已安装包的运行时路径（类似 /usr — 包含 bin/、lib/、include/）
• $FLOX_ENV_CACHE — 持久本地存储，用于缓存、venv、数据（重建后保留）
• $FLOX_ENV_PROJECT — 项目根目录（.flox/ 所在位置）

基本命令

flox init                       # 创建新环境
flox search <package> [--all]   # 搜索可用包
flox show <package>             # 显示包详情
flox install <package>          # 安装包到环境
flox uninstall <package>        # 从环境移除包
flox activate                   # 激活环境
flox list                       # 列出已安装的包
flox edit                       # 编辑 manifest.toml
flox push                       # 推送到 FloxHub
flox pull                       # 从 FloxHub 拉取

Manifest 结构

# .flox/env/manifest.toml
version = 1

[install]
python3.pkg-path = "python311"
nodejs.pkg-path = "nodejs_20"
postgresql.pkg-path = "postgresql_16"
redis.pkg-path = "redis"

[vars]
DATABASE_URL = "postgresql://localhost:5432/myapp"
REDIS_URL = "redis://localhost:6379"

[hook]
on-activate = '''
  # 激活时运行
  echo "Environment ready!"
'''

[services]
postgres.command = "pg_ctl start -D $FLOX_ENV_CACHE/pgdata"
redis.command = "redis-server"

最佳实践

1. 提交 .flox/env/manifest.toml 到版本控制
2. 使用 $FLOX_ENV_CACHE 存储持久数据（数据库文件、venv）
3. 使用 $FLOX_ENV/lib 和 $FLOX_ENV/include 链接原生库
4. 在 hook 中设置 语言特定的虚拟环境
5. 使用 services 管理本地数据库和缓存