Flox Environments 是 Flox Claude Code 插件中的一个技能，用于通过 Flox 创建可复现、跨平台的开发环境。Flox 是一个基于 Nix 的声明式环境管理器，在单个 TOML 清单中定义环境，团队成员可在 macOS 与 Linux 上获得完全一致的软件包、工具与配置，无需容器或虚拟机，并可访问超过 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] 段声明要安装的包；[vars] 段声明静态环境变量；[hook] 段声明非交互式设置脚本（每次激活都运行）；[profile] 段声明 shell 函数与别名（在交互式 shell 中可用）；[options] 段的 systems 声明支持的平台，如 x86_64-linux、aarch64-linux、x86_64-darwin、aarch64-darwin。
【包安装模式】 基础安装通过 [install] 段用 pkg-path 指定包；版本固定通过 version 字段支持 semver 范围（如 ^20.0）或精确版本（如 16.2）；平台特定包通过 systems 字段限定；包冲突通过 priority（数字越小优先级越高）解决，或通过 pkg-group 将应一起解析版本的包分组。
【语言特定配方】 技能提供了 Python with uv、Node.js、Rust、Go、C/C++ 的配方。例如 Python with uv 中，在 [vars] 设置 UV_CACHE_DIR 与 PIP_CACHE_DIR 指向 $FLOX_ENV_CACHE，在 [hook] 的 on-activate 中创建并激活 venv、按需安装依赖。C/C++ 配方指出 gcc 单独不会暴露 libstdc++ 头文件，需要 gcc-unwrapped。
【Hooks 与 Profile】 Hooks 在每次激活时运行，应保持快速且幂等；经验法则：应自动发生的事放入 [hook]，用户应能键入的事放入 [profile]。Profile 代码在用户 shell 会话中可用。
【反模式】 避免使用绝对路径（应使用 Flox 环境变量如 $FLOX_ENV_PROJECT）；避免在 hook 中使用 exit（会杀死 shell，应使用 return）；避免在清单中存储密钥（清单会提交到 git）；避免无幂等保护的慢 hook（应使用标志文件跳过重复安装）；避免将用户命令放入 hook（hook 函数在交互式 shell 中不可用，应使用 [profile]）。
【完整示例】 技能提供了一个 Python API + PostgreSQL 的完整环境示例，包含 [install]、[vars]、[hook]、[profile]、[services] 与 [options] 段，服务包括 postgres 与 redis，可用 flox activate --start-services 激活服务。
【环境共享】 Flox 环境是 git 原生的：提交 .flox/ 目录，每位协作者获得相同环境。可推送到 FloxHub（flox push、flox activate -r owner/env-name）。可通过 [include] 与 base.floxhub 组合环境。
【AI 辅助与 Vibe Coding】 Flox 适合 AI 辅助开发与 vibe coding 工作流。当 AI 智能体需要当前环境中没有的工具时，可将其添加到项目 Flox 清单，无需 sudo、不污染系统包、不受沙箱限制。原因：无需 sudo（flox install 完全在用户空间工作）；项目级作用域（包只安装到项目环境，不同项目可用不同版本而不冲突）；沙箱友好；可逆（所有变更记录在 manifest.toml 中，可干净移除）；可复现。智能体工作流模式示例：flox search jq 验证包存在，flox install jq 安装到项目环境，或用临时清单通过 flox edit -f 应用，再用 flox activate -- jq '.results[]' data.json 运行命令。
【调试】 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。