flox-environments

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Flox Environments

Flox 开发环境

Flox creates reproducible development environments defined in a single TOML manifest. Every developer on the team gets identical packages, tools, and configuration — across macOS and Linux — without containers or VMs. Built on Nix with access to over 150,000 packages.

Flox通过单一TOML清单文件定义可复现的开发环境。团队中的每位开发者都能获得完全相同的软件包、工具和配置——跨macOS和Linux平台——无需容器或虚拟机。Flox基于Nix构建，可访问超过15万个软件包。

When to Activate

适用场景

Use this skill when the user has an environment management problem — even if they haven't mentioned Flox. Flox is the right tool when:

The project needs system-level packages (compilers, databases, CLI tools) alongside language-specific dependencies
Reproducibility matters — the setup should work identically on a teammate's machine, in CI, or on a fresh laptop
The user needs multiple tools to coexist — e.g., Python 3.11 + PostgreSQL 16 + Redis + Node.js in one environment
Cross-platform support is needed (macOS and Linux from the same config)
AI agents need to install tools — Flox lets agents add packages to a project-scoped environment without sudo, system pollution, or sandbox restrictions

If the user just needs a single language runtime with no system dependencies, standard tooling (nvm, pyenv, rustup alone) may suffice. If they need full OS-level isolation, containers might be more appropriate. Flox sits in the sweet spot: declarative, reproducible environments without container overhead.

Prerequisite: Flox must be installed first — see flox.dev/docs for macOS, Linux, and Docker.

当用户遇到环境管理问题时，即便未提及Flox，也可使用此技能。以下场景下Flox是理想工具：

项目需要系统级软件包（编译器、数据库、CLI工具）与语言专属依赖共存
可复现性至关重要——环境配置需在队友机器、CI环境或全新笔记本上完全一致运行
用户需要多工具共存——例如在同一环境中使用Python 3.11 + PostgreSQL 16 + Redis + Node.js
需要跨平台支持（同一配置适配macOS和Linux）
AI Agent需要安装工具——Flox允许Agent将软件包添加到项目级环境中，无需sudo权限、不会污染系统环境，也不受沙箱限制

如果用户仅需单一语言运行时且无系统依赖，标准工具（如单独使用nvm、pyenv、rustup）可能足够。如果需要完整的操作系统级隔离，容器可能更合适。Flox处于中间最优地带：无需容器开销的声明式可复现环境。

前置条件： 需先安装Flox——请查看flox.dev/docs获取macOS、Linux和Docker版本的安装指南。

Core Concepts

核心概念

Flox environments are defined in

.flox/env/manifest.toml

and activated with

flox activate

. The manifest declares packages, environment variables, setup hooks, and shell configuration — everything needed to reproduce the environment anywhere.

Key paths:

```
.flox/env/manifest.toml
```
— Environment definition (commit this)
```
$FLOX_ENV
```
— Runtime path to installed packages (like
```
/usr
```
— contains
```
bin/
```
,
```
lib/
```
,
```
include/
```
)
```
$FLOX_ENV_CACHE
```
— Persistent local storage for caches, venvs, data (survives rebuilds)
```
$FLOX_ENV_PROJECT
```
— Project root directory (where
```
.flox/
```
lives)

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/
```
所在位置）

Essential Commands

核心命令

bash

flox init                       # Create new environment
flox search <package> [--all]   # Search for packages
flox show <package>             # Show available versions
flox install <package>          # Add a package
flox list                       # List installed packages
flox activate                   # Enter environment
flox activate -- <cmd>          # Run a command in the environment without a subshell
flox edit                       # Edit manifest interactively

bash

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

Manifest Structure

清单文件结构

toml

undefined

toml

undefined

.flox/env/manifest.toml

[install]

Packages to install — the core of the environment

要安装的软件包——环境的核心

ripgrep.pkg-path = "ripgrep" jq.pkg-path = "jq"

[vars]

ripgrep.pkg-path = "ripgrep" jq.pkg-path = "jq"

[vars]

Static environment variables

静态环境变量

DATABASE_URL = "postgres://localhost:5432/myapp"

[hook]

DATABASE_URL = "postgres://localhost:5432/myapp"

[hook]

Non-interactive setup scripts (run every activation)

非交互式启动脚本（每次激活时运行）

on-activate = """ echo "Environment ready" """

[profile]

on-activate = """ echo "Environment ready" """

[profile]

Shell functions and aliases (available in interactive shell)

Shell函数和别名（在交互式Shell中可用）

common = """ alias dev="npm run dev" """

[options]

common = """ alias dev="npm run dev" """

[options]

Supported platforms

支持的平台

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

undefined

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

undefined

Package Installation Patterns

软件包安装模式

Basic Installation

基础安装

toml

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

toml

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

Version Pinning

版本固定

toml

[install]
nodejs.pkg-path = "nodejs"
nodejs.version = "^20.0"          # Semver range: latest 20.x

postgres.pkg-path = "postgresql"
postgres.version = "16.2"         # Exact version

toml

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

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

Platform-Specific Packages

平台专属软件包

toml

[install]

toml

[install]

Linux-only tools

仅Linux可用的工具

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

macOS frameworks

macOS框架

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

GNU tools on macOS (where BSD defaults differ)

macOS上的GNU工具（与BSD默认工具不同）

coreutils.pkg-path = "coreutils" coreutils.systems = ["x86_64-darwin", "aarch64-darwin"]

undefined

coreutils.pkg-path = "coreutils" coreutils.systems = ["x86_64-darwin", "aarch64-darwin"]

undefined

Resolving Package Conflicts

解决软件包冲突

When two packages install the same binary, use

priority

(lower number wins):

toml

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

clang.pkg-path = "clang_18"
clang.priority = 5               # gcc wins file conflicts

Use

pkg-group

to group packages that should resolve versions together:

toml

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

pip.pkg-path = "python311Packages.pip"
pip.pkg-group = "python-stack"    # Resolves together with python

当两个软件包安装相同二进制文件时，使用

priority

（数值越小优先级越高）：

toml

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

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

使用

pkg-group

对需协同解析版本的软件包进行分组：

toml

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

pip.pkg-path = "python311Packages.pip"
pip.pkg-group = "python-stack"    # 与python协同解析版本

Language-Specific Recipes

语言专属配置示例

Python with uv

Python 搭配 uv

toml

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

toml

[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

toml

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

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

toml

[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

toml

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

toml

[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

toml

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

toml

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

toml

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

toml

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

IMPORTANT: gcc alone doesn't expose libstdc++ headers — you need gcc-unwrapped

重要提示：仅安装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"]

undefined

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

undefined

Hooks and Profile

钩子与配置文件

Hooks — Non-Interactive Setup

钩子——非交互式启动

Hooks run on every activation. Keep them fast and idempotent. Rule of thumb: if it should happen automatically, put it in
[hook]
; if the user should be able to type it, put it in
[profile]
.

toml

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

钩子在每次激活环境时运行。请保持钩子快速且幂等。经验法则：如果操作应自动执行，放在
[hook]
中；如果需要用户手动输入执行，放在
[profile]
中。

toml

[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 — Interactive Shell Configuration

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

Profile code is available in the user's shell session.

toml

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

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

toml

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

Anti-Patterns

反模式

Absolute Paths

绝对路径

toml

undefined

toml

undefined

BAD — breaks on other machines

错误——在其他机器上会失效

[vars] PROJECT_DIR = "/home/alice/projects/myapp"

GOOD — use Flox environment variables

正确——使用Flox环境变量

[vars] PROJECT_DIR = "$FLOX_ENV_PROJECT"

undefined

[vars] PROJECT_DIR = "$FLOX_ENV_PROJECT"

undefined

Using exit in Hooks

在钩子中使用exit

toml

undefined

toml

undefined

BAD — kills the shell

错误——会终止Shell

[hook] on-activate = """ if [ ! -f config.json ]; then echo "Missing config" exit 1 fi """

GOOD — return from hook, don't exit

正确——从钩子返回，不要退出

[hook] on-activate = """ if [ ! -f config.json ]; then echo "Missing config — run setup first" return 1 fi """

undefined

[hook] on-activate = """ if [ ! -f config.json ]; then echo "Missing config — run setup first" return 1 fi """

undefined

Storing Secrets in Manifest

在清单文件中存储密钥

toml

undefined

toml

undefined

BAD — manifest is committed to git

错误——清单文件会提交到git

[vars] API_KEY = "<set-at-runtime>"

GOOD — reference external config or pass at runtime

正确——引用外部配置或在运行时传入

Use: API_KEY="<your-api-key>" flox activate

使用方式：API_KEY="<your-api-key>" flox activate

[vars] API_KEY = "${API_KEY:-}"

undefined

[vars] API_KEY = "${API_KEY:-}"

undefined

Slow Hooks Without Idempotency Guards

无幂等性校验的慢钩子

toml

undefined

toml

undefined

BAD — reinstalls every activation

错误——每次激活都会重新安装

[hook] on-activate = """ pip install -r requirements.txt """

GOOD — skip if already installed

正确——已安装则跳过

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

undefined

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

undefined

Putting User Commands in Hooks

在钩子中放置用户命令

toml

undefined

toml

undefined

BAD — hook functions aren't available in the interactive shell

错误——钩子中的函数在交互式Shell中不可用

[hook] on-activate = """ deploy() { kubectl apply -f k8s/; } """

GOOD — use [profile] for user-invokable functions

正确——使用[profile]存放用户可调用的函数

[profile] common = """ deploy() { kubectl apply -f k8s/; } """

undefined

[profile] common = """ deploy() { kubectl apply -f k8s/; } """

undefined

Full-Stack Example

全栈示例

A complete environment for a Python API with PostgreSQL:

toml

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

Activate with services:

flox activate --start-services

适用于Python API搭配PostgreSQL的完整环境：

toml

[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

Environment Sharing

环境共享

Flox environments are git-native. Commit the

.flox/

directory and every collaborator gets the same environment:

bash

git add .flox/
git commit -m "Add Flox environment"

Flox环境是原生Git兼容的。提交

.flox/

目录后，每位协作者都能获得相同的环境：

bash

git add .flox/
git commit -m "Add Flox environment"

Teammates just run:

队友只需运行：

git clone <repo> && cd <repo> && flox activate


For reusable base environments across projects, push to FloxHub:

```bash
flox push                         # Push environment to FloxHub
flox activate -r owner/env-name   # Activate remote environment anywhere

Compose environments with

[include]

toml

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

[install]

git clone <repo> && cd <repo> && flox activate


如需在多个项目中复用基础环境，可推送到FloxHub：

```bash
flox push                         # 将环境推送到FloxHub
flox activate -r owner/env-name   # 在任意位置激活远程环境

通过

[include]

组合环境：

toml

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

[install]

Project-specific additions on top of base

在基础环境之上添加项目专属软件包

fastapi.pkg-path = "python311Packages.fastapi"

undefined

fastapi.pkg-path = "python311Packages.fastapi"

undefined

AI-Assisted and Vibe Coding

AI辅助与随性编码

Flox is ideal for AI-assisted development and vibe coding workflows. When an AI agent needs a tool that isn't available in the current environment — a compiler, a database, a linter, a CLI utility — it can add it to the project's Flox manifest without requiring sudo access, polluting system packages, or hitting sandbox restrictions.

Why this matters for agents:

No sudo required —
```
flox install
```
works entirely in user space, so agents can add packages without elevated permissions
Project-scoped — packages are installed into the project environment only, not globally, so different projects can have different versions without conflict
Sandbox-friendly — agents running in sandboxed or restricted environments can still install the tools they need through Flox
Reversible — every change is captured in
```
manifest.toml
```
, so unwanted packages can be removed cleanly with no system residue
Reproducible — when an agent sets up an environment, that exact setup is committed to git and works for everyone

Agent workflow pattern:

bash

undefined

Flox非常适合AI辅助开发和随性编码（vibe coding）工作流。当AI Agent需要当前环境中未安装的工具——编译器、数据库、代码检查器、CLI实用工具——它可以将工具添加到项目的Flox清单文件中，无需sudo权限、不会污染系统软件包，也不受沙箱限制。

这对Agent的重要性：

无需sudo权限——
```
flox install
```
完全在用户空间运行，Agent无需提升权限即可安装软件包
项目级范围——软件包仅安装到项目环境中，而非全局，不同项目可使用不同版本而无冲突
沙箱友好——在沙箱或受限环境中运行的Agent仍可通过Flox安装所需工具
可撤销——所有变更都记录在
```
manifest.toml
```
中，不需要的软件包可干净移除，无系统残留
可复现——Agent搭建的环境会提交到Git，对所有人都能正常运行

Agent工作流模式：

bash

undefined

Agent discovers it needs a tool (e.g., jq for JSON processing)

Agent发现需要某个工具（例如用于JSON处理的jq）

flox search jq # Verify the package exists flox install jq # Install into project environment

flox search jq # 验证软件包是否存在 flox install jq # 安装到项目环境

Or for more control, edit the manifest directly

如需更多控制，可直接编辑清单文件

tmp_manifest="$(mktemp)" flox list -c > "$tmp_manifest"

Add the package to [install] section, then apply

将软件包添加到[install]部分，然后应用变更

flox edit -f "$tmp_manifest"

Run a command with the tool available

使用已安装的工具运行命令

flox activate -- jq '.results[]' data.json


This makes Flox a natural fit for any workflow where Claude Code or other AI agents need to bootstrap project tooling on the fly.

flox activate -- jq '.results[]' data.json


这使得Flox成为Claude Code或其他AI Agent需要动态搭建项目工具链的工作流的自然选择。

Debugging

调试

bash

flox list -c                      # Show raw manifest
flox activate -- which python     # Check which binary resolves
flox activate -- env | grep FLOX  # See Flox environment variables
flox search <package> --all       # Broader package search (case-sensitive)

Common issues:

Package not found: Search is case-sensitive — try
```
flox search --all
```
File conflicts between packages: Add
```
priority
```
to the package that should win
Hook failures: Use
```
return
```
not
```
exit
```
; guard with
```
${FLOX_ENV_CACHE:-}
```
Stale dependencies: Delete the
```
$FLOX_ENV_CACHE/.deps_installed
```
flag file

bash

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
```
标记文件