Flox 环境¶

Flox 创建由单个 TOML 清单定义的可复现开发环境。团队中的所有开发者都能获得相同的软件包、工具和配置 — 在 macOS 和 Linux 之间保持一致，且无需容器或 VM。它构建在可访问 150,000 多个软件包的 Nix 之上。

何时激活¶

当用户面临环境管理问题时，即使他们没有提到 Flox，也应使用此技能。Flox 成为合适工具的情况包括：

项目需要系统级软件包（编译器、数据库、CLI 工具）以及语言特定依赖时
可复现性很重要 — 需要在团队成员的机器、CI 或新笔记本电脑上以相同方式运行时
用户需要多种工具共存 — 例如在一个环境中使用 Python 3.11 + PostgreSQL 16 + Redis + Node.js
需要跨平台支持（从同一配置用于 macOS 和 Linux）
AI 代理需要安装工具 — Flox 允许代理无需 sudo、不污染系统、不受沙箱限制，即可向项目范围的环境中添加软件包

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

前提条件： 首先需要安装 Flox — 关于 macOS、Linux、Docker，请参阅 flox.dev/docs。

核心概念¶

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 list                       # インストール済みパッケージを一覧表示
flox activate                   # 環境に入る
flox activate -- <cmd>          # サブシェルなしで環境内でコマンドを実行
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 "Environment ready"
"""

[profile]
# シェル関数とエイリアス（インタラクティブシェルで利用可能）
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と一緒に解決

语言特定配方¶

使用 uv 的 Python¶

[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¶

# 悪い例 — シェルを終了させる
[hook]
on-activate = """
  if [ ! -f config.json ]; then
    echo "Missing config"
    exit 1
  fi
"""

# 良い例 — exitではなくreturnを使用
[hook]
on-activate = """
  if [ ! -f config.json ]; then
    echo "Missing config — run setup first"
    return 1
  fi
"""

将密钥保存到清单¶

# 悪い例 — マニフェストはgitにコミットされる
[vars]
API_KEY = "<set-at-runtime>"

# 良い例 — 外部設定を参照するか、ランタイムで渡す
# 使用方法: 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
"""

将用户命令放入钩子¶

# 悪い例 — フック関数はインタラクティブシェルで利用できない
[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 "Add Flox environment"
# チームメイトは以下を実行するだけ:
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 辅助与氛围编程¶

Flox 非常适合 AI 辅助开发和氛围编程工作流。当 AI 代理需要当前环境中不可用的工具（编译器、数据库、代码检查器、CLI 实用工具）时，无需 sudo 访问、不污染系统包、不受沙箱限制，即可将其添加到项目的 Flox 清单中。

这对代理重要的原因： - 无需 sudo — flox install 完全在用户空间运行，因此代理无需提升权限即可添加包 - 项目范围 — 包只安装到项目环境中，而不是全局安装，因此不同项目可以拥有不同版本且互不冲突 - 沙箱友好 — 在沙箱或受限环境中运行的代理也可以通过 Flox 安装所需工具 - 可回滚 — 所有更改都记录在 manifest.toml 中，因此可以干净地移除不需要的包，不会留下系统残留 - 可复现 — 当代理设置环境后，其精确设置会提交到 git，任何人都可以使用

代理工作流模式：

# エージェントがツールが必要だと発見する（例: JSON処理のためのjq）
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。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 ev/ECC