flox-environments

Flox 環境（Flox Environments）

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 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"]

Hooks 和 Profile

Hooks —— 非互動式設定

Hooks 在每次啟動時執行。請保持它們快速且冪等。經驗法則：如果應該自動發生，請放在 [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
"""

Profile —— 互動式 Shell 配置

Profile 程式碼在使用者的 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"

在 Hook 中使用 exit

# 錯誤——會終止 shell
[hook]
on-activate = """
  if [ ! -f config.json ]; then
    echo "缺少設定檔"
    exit 1
  fi
"""

# 正確——從 hook 返回，不要 exit
[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

# 錯誤——每次啟動都重新安裝
[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 中

# 錯誤——hook 函式在互動式 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 輔助與 Vibe Coding

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

為什麼這對代理很重要：

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

代理工作流程模式：

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

# 或者為了更精確的控制，直接編輯清單
临时清单="$(mktemp)"
flox list -c > "$临时清单"
# 將套件新增到 [install] 區段，然後套用
flox edit -f "$临时清单"

# 使用該工具執行指令
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
• Hook 失敗： 使用 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