开发容器¶

面向维护者。正在使用 T3 Code？请参阅 docs/user。

.devcontainer/ 为你提供了一个与 CI 匹配、开箱即用的 Linux 环境：Ubuntu 24.04、Node 26、pnpm、Rust stable、全局 vp CLI 和 GitHub CLI。在 VS Code 中打开仓库，然后选择“在容器中重新打开”（Reopen in Container），或创建一个 GitHub Codespace。依赖安装（vp i）、Electron 可执行位修复和 Vite 依赖缓存预热都会在你连接之前自动运行。

容器中可用的功能¶

• 完整的开发栈：运行 vp run dev，然后通过转发的 Web 端口（5733）打开它打印出的配对 URL。没有配对 token，裸 origin 毫无用处。在 VS Code 中，转发端口是真正的 localhost，因此打印出的 URL 可以直接使用；在浏览器版 Codespaces 中，转发的 origin 有所不同，如果服务器拒绝它，请通过 T3CODE_DEV_ALLOWED_ORIGINS 传入转发的 origin。

• Linux CI 作业运行的全部内容：定向的 vp test run <files>、vp lint <files>、各包的类型检查、vp run build:desktop，以及 resource-monitor 的 cargo 构建和测试。（vpr 不在此处的 PATH 上；curl 安装器只为 vp 做 shim。安装后请使用 vp run <script> 或 node_modules/.bin/vpr。）

状态与安全¶

T3CODE_HOME 指向工作区中已被 gitignore 的 .t3，因此所有运行时状态都保留在容器工作区内，与 worktree 的默认行为保持一致。容器内没有可损坏的实时安装，但 AGENTS.md 中的测试数据规则仍然适用：请将数据复制进来，绝不要指向共享状态。

缓存¶

两个命名卷让重建保持快速，并把安装移出缓慢的 macOS/Windows bind mount：pnpm store（在不同 checkout 之间共享，挂载在 vp i 存放它的位置）和根目录 node_modules（按容器隔离，覆盖整个 .pnpm 虚拟存储，因为工作区包只是符号链接到其中）。删除并重新创建容器时会同时复用这两者，因此一次重建中的 vp i 只需几秒，而不是几分钟。宿主机看到的 node_modules 是空的；请在容器内运行宿主机侧的工具。

不在范围内¶

• Electron 窗口应用的开发仅限宿主机。在容器中构建并验证 desktop bundle 完全没有问题（CI 正是这样做的，以无头模式运行）；启动应用需要有显示器。

• 移动端原生构建仅限宿主机（iOS 用 Xcode，Android 用 Android SDK）。类型检查、lint 和移动端静态检查均可正常运行。

• vp run dev --share 需要 tailscale 二进制文件和 tailnet；此处未提供。

预构建¶

从头创建容器会执行完整的 vp i 以及工具链安装，因此值得做预构建。Codespaces 的预构建在仓库设置中配置，而不是在文件中配置，并且会原样采用此配置：重步骤都在 onCreateCommand 和 updateContentCommand 中，预构建会将其固化。请将预构建限制在一个区域和一个保留版本；存储按区域、按版本计费。请注意，预构建快照不包含缓存卷，因此以预构建为先的工作流可能更倾向于移除这些挂载。在 Codespaces 之外，Dev Container CLI 可以推送预构建镜像：

devcontainer build --workspace-folder . --push true --image-name <registry>/t3code-devcontainer:latest