flox-environments

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 —— 用于缓存、虚拟环境、数据的持久本地存储（在重建后仍然存在）
• $FLOX_ENV_PROJECT —— 项目根目录（.flox/ 所在的位置）

基本命令

flox init                       # 创建新环境
flox search <package> [--all]   # 搜索软件包
flox show <package>             # 显示可用版本
flox install <package>          # 添加软件包
flox list                       # 列出已安装的软件包
flox activate                   # 进入环境
flox activate -- <cmd>          # 在环境中运行命令，不启动子 shell
flox edit                       # 交互式编辑清单

清单结构

# .flox/env/manifest.toml

[install]
# 要安装的软件包——环境的核心
ripgrep.pkg-path = "ripgrep"
jq.pkg-path = "jq"

[vars]
# 静态环境变量
DATABASE_URL = "postgres://localhost:5432/myapp"

[hook]
# 非交互式设置脚本（每次激活时运行）
on-activate = """
  echo "环境已就绪"
"""

[profile]
# shell 函数和别名（在交互式 shell 中可用）
common = """
  alias dev="npm run dev"
"""

[options]
# 支持的平台
systems = ["x86_64-linux", "aarch64-linux", "x86_64-darwin", "aarch64-darwin"]

软件包安装模式

基本安装

[install]
nodejs.pkg-path = "nodejs"
python.pkg-path = "python311"
rustup.pkg-path = "rustup"

版本锁定

[install]
nodejs.pkg-path = "nodejs"
nodejs.version = "^20.0"          # Semver 范围：最新的 20.x

postgres.pkg-path = "postgresql"
postgres.version = "16.2"         # 精确版本

特定平台的软件包

[install]
# Linux 专用工具
valgrind.pkg-path = "valgrind"
valgrind.systems = ["x86_64-linux", "aarch64-linux"]

# macOS 框架
Security.pkg-path = "darwin.apple_sdk.frameworks.Security"
Security.systems = ["x86_64-darwin", "aarch64-darwin"]

# macOS 上的 GNU 工具（BSD 默认工具不同）
coreutils.pkg-path = "coreutils"
coreutils.systems = ["x86_64-darwin", "aarch64-darwin"]

解决软件包冲突

当两个软件包安装相同的二进制文件时，使用 priority（数字越小优先级越高）：

[install]
gcc.pkg-path = "gcc12"
gcc.priority = 3

clang.pkg-path = "clang_18"
clang.priority = 5               # gcc 在文件冲突中获胜

使用 pkg-group 将应一起解析版本的软件包分组：

[install]
python.pkg-path = "python311"
python.pkg-group = "python-stack"

pip.pkg-path = "python311Packages.pip"
pip.pkg-group = "python-stack"    # 与 python 一起解析

特定语言的配置方案

Python + uv

[install]
python.pkg-path = "python311"
uv.pkg-path = "uv"

[vars]
UV_CACHE_DIR = "$FLOX_ENV_CACHE/uv-cache"
PIP_CACHE_DIR = "$FLOX_ENV_CACHE/pip-cache"

[hook]
on-activate = """
  venv="$FLOX_ENV_CACHE/venv"
  if [ ! -d "$venv" ]; then
    uv venv "$venv" --python python3
  fi
  if [ -f "$venv/bin/activate" ]; then
    source "$venv/bin/activate"
  fi

  if [ -f requirements.txt ] && [ ! -f "$FLOX_ENV_CACHE/.deps_installed" ]; then
    uv pip install --python "$venv/bin/python" -r requirements.txt --quiet
    touch "$FLOX_ENV_CACHE/.deps_installed"
  fi
"""

Node.js

[install]
nodejs.pkg-path = "nodejs"
nodejs.version = "^20.0"

[hook]
on-activate = """
  if [ -f package.json ] && [ ! -d node_modules ]; then
    npm install --silent
  fi
"""

Rust

[install]
rustup.pkg-path = "rustup"
pkg-config.pkg-path = "pkg-config"
openssl.pkg-path = "openssl"

[vars]
RUSTUP_HOME = "$FLOX_ENV_CACHE/rustup"
CARGO_HOME = "$FLOX_ENV_CACHE/cargo"

[profile]
common = """
  export PATH="$CARGO_HOME/bin:$PATH"
"""

Go

[install]
go.pkg-path = "go"
gopls.pkg-path = "gopls"
delve.pkg-path = "delve"

[vars]
GOPATH = "$FLOX_ENV_CACHE/go"
GOBIN = "$FLOX_ENV_CACHE/go/bin"

[profile]
common = """
  export PATH="$GOBIN:$PATH"
"""

C/C++

[install]
gcc.pkg-path = "gcc13"
gcc.pkg-group = "compilers"

# 重要提示：仅 gcc 不会暴露 libstdc++ 头文件——你需要 gcc-unwrapped
gcc-unwrapped.pkg-path = "gcc-unwrapped"
gcc-unwrapped.pkg-group = "libraries"

cmake.pkg-path = "cmake"
cmake.pkg-group = "build"

gnumake.pkg-path = "gnumake"
gnumake.pkg-group = "build"

gdb.pkg-path = "gdb"
gdb.systems = ["x86_64-linux", "aarch64-linux"]

钩子与配置文件

钩子——非交互式设置

钩子在每次激活时运行。保持它们快速且幂等。经验法则：如果需要自动发生，放在 [hook] 中；如果用户应该能够输入，放在 [profile] 中。

[hook]
on-activate = """
  setup_database() {
    if [ ! -d "$FLOX_ENV_CACHE/pgdata" ]; then
      initdb -D "$FLOX_ENV_CACHE/pgdata" --no-locale --encoding=UTF8
    fi
  }
  setup_database
"""

配置文件——交互式 Shell 配置

配置文件中的代码在用户的 shell 会话中可用。

[profile]
common = """
  dev() { npm run dev; }
  test() { npm run test -- "$@"; }
"""

反模式

绝对路径

# 错误——在其它机器上会出错
[vars]
PROJECT_DIR = "/home/alice/projects/myapp"

# 正确——使用 Flox 环境变量
[vars]
PROJECT_DIR = "$FLOX_ENV_PROJECT"

在钩子中使用 exit

# 错误——会杀死 shell
[hook]
on-activate = """
  if [ ! -f config.json ]; then
    echo "缺少配置文件"
    exit 1
  fi
"""

# 正确——从钩子返回，不要退出
[hook]
on-activate = """
  if [ ! -f config.json ]; then
    echo "缺少配置文件——请先运行设置"
    return 1
  fi
"""

在清单中存储密钥

# 错误——清单会被提交到 git
[vars]
API_KEY = "<运行时设置>"

# 正确——引用外部配置或运行时传递
# 使用：API_KEY="<your-api-key>" flox activate
[vars]
API_KEY = "${API_KEY:-}"

没有幂等保护的慢钩子

# 错误——每次激活都重新安装
[hook]
on-activate = """
  pip install -r requirements.txt
"""

# 正确——如果已安装则跳过
[hook]
on-activate = """
  if [ ! -f "$FLOX_ENV_CACHE/.deps_installed" ]; then
    uv pip install -r requirements.txt --quiet
    touch "$FLOX_ENV_CACHE/.deps_installed"
  fi
"""

将用户命令放在钩子中

# 错误——钩子函数在交互式 shell 中不可用
[hook]
on-activate = """
  deploy() { kubectl apply -f k8s/; }
"""

# 正确——对用户可调用的函数使用 [profile]
[profile]
common = """
  deploy() { kubectl apply -f k8s/; }
"""

全栈示例

一个包含 PostgreSQL 的 Python API 的完整环境：

[install]
python.pkg-path = "python311"
uv.pkg-path = "uv"
postgresql.pkg-path = "postgresql_16"
redis.pkg-path = "redis"
jq.pkg-path = "jq"
curl.pkg-path = "curl"

[vars]
UV_CACHE_DIR = "$FLOX_ENV_CACHE/uv-cache"
DATABASE_URL = "postgres://localhost:5432/myapp"
REDIS_URL = "redis://localhost:6379"

[hook]
on-activate = """
  if [ ! -d "$FLOX_ENV_CACHE/pgdata" ]; then
    initdb -D "$FLOX_ENV_CACHE/pgdata" --no-locale --encoding=UTF8
  fi

  venv="$FLOX_ENV_CACHE/venv"
  if [ ! -d "$venv" ]; then
    uv venv "$venv" --python python3
  fi
  if [ -f "$venv/bin/activate" ]; then
    source "$venv/bin/activate"
  fi

  if [ -f requirements.txt ] && [ ! -f "$FLOX_ENV_CACHE/.deps_installed" ]; then
    uv pip install --python "$venv/bin/python" -r requirements.txt --quiet
    touch "$FLOX_ENV_CACHE/.deps_installed"
  fi
"""

[profile]
common = """
  serve() { uvicorn app.main:app --reload --host 0.0.0.0 --port 8000; }
  migrate() { alembic upgrade head; }
"""

[services]
postgres.command = "postgres -D $FLOX_ENV_CACHE/pgdata -k $FLOX_ENV_CACHE"
redis.command = "redis-server --port 6379 --daemonize no"

[options]
systems = ["x86_64-linux", "aarch64-linux", "x86_64-darwin", "aarch64-darwin"]

使用服务激活：flox activate --start-services

环境共享

Flox 环境天生与 git 集成。将 .flox/ 目录提交，每位协作者都能获得相同环境：

git add .flox/
git commit -m "添加 Flox 环境"
# 团队成员只需运行：
git clone <repo> && cd <repo> && flox activate

若要跨项目重用基础环境，可推送到 FloxHub：

flox push                         # 将环境推送到 FloxHub
flox activate -r owner/env-name   # 在任何地方激活远程环境

使用 [include] 组合环境：

[include]
base.floxhub = "myorg/python-base"

[install]
# 在基础环境之上添加项目特定的软件包
fastapi.pkg-path = "python311Packages.fastapi"

AI 辅助与 Vibe Coding

Flox 非常适合 AI 辅助开发和 vibe coding 工作流。当 AI 代理需要当前环境中不存在的工具——编译器、数据库、代码检查工具、CLI 实用程序——它可以将其添加到项目的 Flox 清单中，而无需 sudo 权限、不会污染系统包或受沙箱限制。

这对代理为何重要：

• 无需 sudo —— flox install 完全在用户空间工作，代理可以在没有提升权限的情况下添加软件包
• 项目作用域 —— 软件包仅安装到项目环境中，而不是全局安装，因此不同项目可以有不同版本而不会冲突
• 沙箱友好 —— 在沙箱或受限环境中运行的代理仍然可以通过 Flox 安装所需的工具
• 可逆 —— 每次更改都记录在 manifest.toml 中，因此不需要的软件包可以干净地移除，不会在系统中留下残留
• 可重现 —— 当代理设置环境时，该精确设置会被提交到 git，并对所有人有效

代理工作流模式：

# 代理发现它需要一个工具（例如 jq 用于 JSON 处理）
flox search jq                    # 确认软件包存在
flox install jq                   # 安装到项目环境中

# 或者为了更精确的控制，直接编辑清单
tmp_manifest="$(mktemp)"
flox list -c > "$tmp_manifest"
# 将软件包添加到 [install] 部分，然后应用
flox edit -f "$tmp_manifest"

# 使用可用工具运行命令
flox activate -- jq '.results[]' data.json

这使得 Flox 自然适用于任何需要 Claude Code 或其他 AI 代理动态引导项目工具链的工作流。

调试

flox list -c                      # 显示原始清单
flox activate -- which python     # 检查哪个二进制文件被解析
flox activate -- env | grep FLOX  # 查看 Flox 环境变量
flox search <package> --all       # 更广泛的软件包搜索（区分大小写）

常见问题：

• 未找到软件包： 搜索区分大小写——尝试 flox search --all
• 软件包之间文件冲突： 为应获胜的软件包添加 priority
• 钩子失败： 使用 return 而不是 exit；使用 ${FLOX_ENV_CACHE:-} 进行保护
• 过时的依赖： 删除 $FLOX_ENV_CACHE/.deps_installed 标记文件

相关技能

以下技能作为 Flox Claude Code 插件 的一部分提供，用于更深度的集成：

• flox-services —— 服务管理、数据库设置、后台进程
• flox-builds —— 使用 Flox 进行可重现的构建和打包
• flox-containers —— 从 Flox 环境创建 Docker/OCI 容器
• flox-sharing —— 环境组合、远程环境、团队模式
• flox-cuda —— CUDA 和 GPU 开发环境

了解更多并在 flox.dev/docs 安装