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 一起解析

語言特定配方

使用 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

# 不好——會終止 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 = "<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
"""

將使用者指令放在掛鉤中

# 不好——掛鉤函式在互動式 shell 中不可用
[hook]
on-activate = """
  deploy() { kubectl apply -f k8s/; }
"""

# 好——使用 [profile] 來放置使用者可呼叫的函式
[profile]
common = """
  deploy() { kubectl apply -f k8s/; }
"""

全端範例

一個完整的 Python API 搭配 PostgreSQL 環境：

[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 輔助與氛圍編程

Flox 非常適合 AI 輔助開發和氛圍編程工作流程。當 AI 代理需要當前環境中沒有的工具時——編譯器、資料庫、linter、CLI 工具——它可以將其新增到專案的 Flox 清單中，而無需 sudo 存取權限、污染系統套件或受到沙箱限制。

這對代理為何重要：

• 不需要 sudo——flox install 完全在使用者空間中運作，因此代理可以在沒有提升權限的情況下新增套件
• 專案範圍——套件僅安裝到專案環境中，而非全域安裝，因此不同的專案可以有不同的版本而不會衝突
• 對沙箱友善——在沙箱或受限環境中運作的代理仍然可以透過 Flox 安裝所需的工具
• 可逆——每個變更都會被記錄在 manifest.toml 中，因此可以乾淨地移除不需要的套件，不留系統殘留
• 可重現——當代理設定環境時，該確切設定會被提交到 git 並適用於所有人

代理工作流程模式：

# 代理發現它需要一個工具（例如，用於 JSON 處理的 jq）
flox search jq                    # 驗證套件是否存在
flox install jq                   # 安裝到專案環境中

# 或者為了更精確的控制，直接編輯清單
clear_manifest="$(mktemp)"
flox list -c > "$clear_manifest"
# 將套件新增到 [install] 區段，然後套用
flox edit -f "$clear_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 了解更多資訊並安裝