基于 Debian + Docker 的通用便携开发工作台:构建一次,处处一致,宿主机零污染(除 Docker 引擎本身)。
宿主机(仅需 Docker + 终端模拟器 + Nerd Font)
└─ kitty/任意终端 ──> docker run -it ──> 容器内 zsh + tmux + nvim
└─ 挂载 $PWD 为 /workspace
- 配置烧进镜像:
config/下所有 zsh/tmux/nvim 配置在构建期 COPY 进镜像,任何机器拉同一镜像得到字节级一致的环境 - 开箱即用(运行时零网络):除 claude code 需要 API 外,运行期不发起任何下载——zsh 插件、nvim 插件(lazy.nvim + lockfile)、treesitter parser、LSP(clangd/pyright/ruff)、blink.cmp 预编译库、rust-analyzer 全部构建期固化;lazy checker 已关闭
- 密钥不进镜像:
ANTHROPIC_AUTH_TOKEN等经.toolbox.env运行时注入 - UID 对齐:entrypoint 自动将容器内
dev用户对齐宿主机 UID/GID,workspace 文件属主正确 - 剪贴板:OSC52 协议桥接(tmux + nvim 双侧),无 X11 依赖,经宿主终端写入系统剪贴板
# 网络稳定环境(直连 GitHub)
sudo docker build -t devtoolbox:latest .
# GitHub 下载不稳时走镜像(推荐国内网络)
sudo docker build --build-arg GH_MIRROR=gh-proxy.com/ -t devtoolbox:latest .
# npm 源不稳时加镜像
sudo docker build --build-arg GH_MIRROR=gh-proxy.com/ \
--build-arg NPM_REGISTRY=https://registry.npmmirror.com \
-t devtoolbox:latest .GH_MIRROR 同时作用于:二进制下载(nvim/lazygit/starship)、全部 git clone(zsh 插件、lazy.nvim 及其插件、treesitter)、mason LSP 下载。
NPM_REGISTRY 作用于 claude code 的 npm 安装。
# 方式一:docker compose(挂载当前目录为 workspace)
sudo docker compose run --rm toolbox
# 方式二:直接 docker run
sudo docker run -it --rm \
-v "$PWD":/workspace \
-e HOST_UID=$(id -u) -e HOST_GID=$(id -g) \
--env-file .toolbox.env \
devtoolbox:latestcp .toolbox.env.example .toolbox.env
# 编辑 .toolbox.env,填入 ANTHROPIC_AUTH_TOKEN(该文件已被 .gitignore 排除)claude.zsh 中其余非机密环境变量(BASE_URL、模型映射)已在镜像内;密钥由 .toolbox.env 注入。
配置分两种改法:
- 临时调试(免重建):bind mount 覆盖镜像内配置
sudo docker run -it --rm \ -v "$PWD":/workspace \ -v "$PWD/config/nvim":/home/dev/.config/nvim \ devtoolbox:latest
- 固化(正式更新):改完验证满意后
sudo docker build ...重新烧进镜像,所有机器下次拉取即更新
zsh 插件更新:zsh-plugin-versions 里改 commit,重建镜像。(容器内 zplugin-update 因插件目录属 root 不可用——按设计,更新走镜像重建。)
从宿主同步配置后,需重新应用的容器适配清单:
.zshrc:剔除 fzf Ubuntu 块;va/input 由DEVTOOLBOX守卫跳过claude.zsh:不含 AUTH_TOKEN(运行时 env-file 注入)lazy.lua:checker = falsetreesitter.lua:prefer_git = truemason.lua/blink.lua:保留镜像 env 支持init.lua:保留pcall(require, "config.clipboard")aliases.zsh:sudovi需 sudo 守卫;starship.toml保留 Debian 符号
Claude Code 更新:同样走镜像重建——npm install -g 每次构建取最新版;需锁版本时把 Dockerfile 里的 @anthropic-ai/claude-code 改为 @anthropic-ai/claude-code@<version>。容器内不做运行时自更新(与「环境一致」目标冲突)。
| 类别 | 内容 |
|---|---|
| Shell | zsh + 自制极简插件管理器(autosuggestions / history-substring-search / vi-mode / syntax-highlighting)+ starship |
| 复用工具 | tmux、lazygit、w3m、fzf、fd、bat、eza、rg、zoxide |
| 编辑器 | nvim 官方最新版 + lazy.nvim(lockfile 锁版本)+ blink.cmp + treesitter + LSP(clangd/pyright/ruff)+ vimtex |
| AI | Claude Code CLI(npm 安装,安装到 ~/.local/bin),经 DeepSeek API 端点;claude-code.nvim 内嵌调用 |
| 工具链 | build-essential、clang-format、nodejs、rustup + rust-analyzer、gdb-multiarch、openocd(ARM 嵌入式)、tectonic(LaTeX 编译) |
- 按键重映射不在此项目内:CapsLock→Esc 等键位由宿主 OS/终端处理,容器与 zsh/tmux 均无法捕获 CapsLock。若需要「仅终端内生效」,宿主 kitty 配置两行即可(零守护进程):
map caps_lock escape map shift+caps_lock caps_lock - 嵌入式调试:openocd + gdb-multiarch 已内置,但调试器硬件访问需 USB 直通,按需加
--privileged -v /dev/bus/usb:/dev/bus/usb - LaTeX:容器用 tectonic 编译(与宿主 texlive 源码兼容);PDF 查看器(zathura)无法容器化,在宿主机查看产物
- nvim 剪贴板粘贴:OSC52 仅支持容器→宿主剪贴板复制;从宿主粘贴请用终端的粘贴快捷键
- 镜像体积约 2.5GB(nvim 插件 + LSP + rust 工具链;插件 git 历史已在构建期剥离)