Devbox Quickstart 上手：从 devbox.json 到可复现的开发环境

• 开发工具
• CLI

本篇技术指南以仓库中的 examples/tutorial/README.md 为主线，围绕一个真实的快速上手示例展开：如何通过devbox.json声明依赖包、利用init_hook初始化环境、以及用devbox run运行自定义脚本。读完本文，你将掌握 Devbox 环境管理的完整工作流——安装与移除包、编写与执行脚本、理解底层锁文件机制，并能独立搭建自己的可复现开发环境。

一、示例项目结构：这个 Quickstart 究竟展示了什么

仓库中的示例位于 examples/tutorial/，它由三部分构成：

• examples/tutorial/devbox.json —— 项目的环境声明文件，定义了安装哪些包、进入环境时执行什么、提供哪些脚本；
• examples/tutorial/devbox.lock —— 由 Devbox 自动生成的锁文件，将每个包固定到精确的 Nix 提交与 store 路径；
• examples/tutorial/README.md —— 指南正文，也就是本篇文章讲解的核心内容。

1.1 devbox.json：环境即代码

示例的devbox.json完整内容如下：

{ "packages": [ "gh", "glow", "vim@latest" ], "shell": { "init_hook": [ "clear && PAGER=cat glow README.md" ], "scripts": { "readme": "clear && PAGER=cat glow README.md" } } }

这份配置表达了三个核心概念：

1. packages：声明需要安装的包。这里安装了gh（GitHub CLI）、glow（终端 Markdown 渲染器）和vim。注意vim@latest使用了@版本语法，表明安装最新版；而gh、glow未指定版本则使用默认版本。
2. shell.init_hook：进入 Devbox 环境（devbox shell）或每次devbox run时自动执行的初始化命令。这里的作用是先清屏，再用glow以纯文本方式渲染README.md，让用户一进入环境就看到这份帮助文档。
3. shell.scripts：定义项目脚本。readme脚本与init_hook内容相同，意味着用户可以随时通过devbox run readme重新回放这份帮助文本。

1.2 devbox.lock：可复现性的基石

devbox.lock由 Devbox 自动生成与维护，用户不需要手工编辑。查看 examples/tutorial/devbox.lock 可以看到它把每个包固定到了精确的 Nix 仓库提交上，例如：

• gh被解析为github:NixOS/nixpkgs/75a52265bda7fd25e06e3a67dee3f0354e73243c#gh；
• vim@latest则记录了last_modified、解析后的具体版本号（如9.2.0782）以及各平台（aarch64-darwin、aarch64-linux、x86_64-linux）的 store 路径。

这意味着只要提交devbox.json和devbox.lock到版本库，团队里每一位成员都能拿到完全一致的工具版本——这正是"instant, easy, and predictable development environments"（项目口号）背后锁文件所发挥的作用。

二、Adding New Packages：安装与移除包

指南的第一部分操作是包管理。核心命令有两个：

devbox add <package> # 安装新包 devbox rm <package> # 移除包

2.1 用 devbox add 安装 Python 3.10

指南给出的实战例子是安装 Python 3.10：

devbox add python310

2.2 add/rm 的底层行为（源码视角）

devbox add与devbox rm的实现分别位于 internal/boxcli/add.go 和 internal/boxcli/rm.go。两者都会先调用devbox.Open打开项目，再执行box.Add(...)与box.Remove(...)。

以add为例，internal/boxcli/add.go 还暴露了一组实用选项：

而在 internal/devbox/packages.go 的Add实现里，流程是：先对包去重、校验包是否存在于搜索端点，再把包名写入devbox.json（PackageMutator().Add），随后调用ensureStateIsUpToDate真正把包安装到 Nix store，最后保存配置。整个流程会同步更新devbox.lock，保证环境状态始终一致。

2.3 包的搜索来源

指南提到：Devbox 可以通过 Nix 包管理器安装超过 80,000 个包。在仓库源码中，搜索能力由devbox search命令承载（见 internal/boxcli/search.go），它对传入的包名调用搜索客户端并打印结果与可用版本。仓库另有一份 SEARCH_API.md 对搜索 API 做了专门说明。搜索到包名之后，再回到devbox add安装即可。

三、Running Devbox Scripts：编写与运行脚本

指南的第二部分讲解脚本机制：在devbox.json中定义脚本，然后用devbox run <script>执行。

3.1 脚本定义与运行

回到示例，在shell.scripts里定义的readme脚本：

devbox run readme

就会执行：

clear && PAGER=cat glow README.md

3.2 run 命令的三种形态（源码视角）

查看 internal/boxcli/run.go 可知，devbox run [<script> | <cmd>]实际上接受三类参数：

1. 项目脚本名：如devbox run readme。若脚本名不存在于devbox.json，则被当作普通命令解释。
2. 任意命令：如devbox run cowsay hello，Devbox 会为它创建一个带全部包环境的临时 shell 并执行。
3. --之后的参数：devbox run -- cowsay -d hello，--之后的全部内容会原样传递给命令，避免被当作 Devbox 自身标志。

另外还有几个实用标志：

• -l/--list：列出devbox.json中定义的全部脚本（无参数直接运行devbox run也会进入此列表模式）；
• --pure：以几乎隔离的环境运行脚本，仅保留HOME、USER、DISPLAY等少量变量；
• --all-projects：递归地在工作目录下所有项目中执行命令。

从实现看，脚本先经 internal/devbox/shellgen/scripts.go 写入脚本文件，再由 internal/devbox/devbox.go 的RunScript在 Nix 环境中执行。值得一提的是：所有脚本与命令都固定从项目根目录（即devbox.json所在目录）运行，如果从子目录调用并需要在子目录执行，需要自己cd进去，例如devbox run -- sh -c 'cd subdir && <command>'。

3.3 脚本的两种书写格式

在devbox.json中，脚本既可以是单行字符串，也可以是字符串数组。底层解析由 internal/devbox/shellcmd/command.go 完成，它会自动保留原始书写格式（字符串按原样还原、数组按数组还原）。两种写法等价，可按可读性自由选择：

"scripts": { "one-liner": "echo hello", "multi-step": [ "echo step 1", "echo step 2" ] }

四、init_hook 与脚本的配合：示例的运行效果

示例项目最有意思的地方在于init_hook与readme脚本内容完全一致。这带来两个使用场景：

1. 进入环境即见文档：执行devbox shell进入环境时，init_hook自动运行，清屏并用glow渲染README.md，第一眼就能看到完整的指南；
2. 随时回放文档：执行devbox run readme，即使在环境之外，也能立刻重温这份帮助文本。

init_hook的解析位置在 internal/devconfig/configfile/file.go 的shellConfig结构中（字段init_hook），其定位是"在 shell 启动时运行的命令"。对devbox run而言，internal/devbox/devbox.go 会设置DEVBOX_SKIP_INIT_HOOK环境变量，确保已在 shell 内执行时不重复运行钩子——这是源码层面可见的一个防重复机制细节。

五、Next Steps：继续深入

指南在最后给出了后续学习方向。结合当前仓库，你可以从以下几条路径继续深入：

• 阅读项目主 README：README.md 中的 Quickstart 讲解了完整的devbox init→devbox add→devbox shell流程，以及环境隔离、版本冲突、可移植性等设计理念；
• 浏览更多示例：仓库的 examples/ 目录覆盖了大量真实场景，例如 examples/development/python/pip/、examples/development/nodejs/nodejs-npm/ 等，可以直观看到不同语言生态的devbox.json写法；
• 查看 CLI 命令全集：运行devbox help可看到所有命令。仓库中 internal/boxcli/ 目录是各子命令的实现源码，devbox add、devbox rm、devbox run、devbox shell均可在其中找到对应实现；
• 阅读测试脚本：testscripts/basic/install_hello.test.txt 这类测试脚本展示了一个最小流程：devbox init→devbox add hello→devbox run hello并校验输出Hello, world!，是理解 Devbox 端到端行为的最小闭环样例。

六、小结

这个 Quickstart 示例虽然短小，却浓缩了 Devbox 的三个核心工作流：

1. 包管理：devbox add/devbox rm声明式地增减依赖，devbox.lock保证可复现；
2. 脚本化：shell.scripts+devbox run把项目常用操作固化为可共享的命令；
3. 环境自动化：shell.init_hook让环境在进入时自动就绪，配合glow这类包，甚至能把项目文档直接"渲染"进终端。

掌握这三个要素，你就能把任意项目的开发环境声明成一份devbox.json，让每位协作者都拥有一致的、即开即用的开发环境。

• 开发工具
• CLI