559 lines
13 KiB
Markdown
559 lines
13 KiB
Markdown
# DevPack 用户手册
|
||
|
||
> 版本：v0.1.0
|
||
> 更新日期：2026-03-03
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
1. [简介](#1-简介)
|
||
2. [安装](#2-安装)
|
||
3. [快速入门](#3-快速入门)
|
||
4. [核心概念](#4-核心概念)
|
||
5. [命令详解](#5-命令详解)
|
||
6. [使用场景](#6-使用场景)
|
||
7. [配置文件](#7-配置文件)
|
||
8. [常见问题](#8-常见问题)
|
||
9. [故障排除](#9-故障排除)
|
||
|
||
---
|
||
|
||
## 1. 简介
|
||
|
||
DevPack 是一个开发环境打包迁移工具。它可以：
|
||
|
||
- 🔍 **扫描** 你当前电脑上安装的开发工具、配置、环境变量等
|
||
- 📦 **打包** 成一个可移植的 `.devpack` 文件
|
||
- 🚀 **还原** 在另一台电脑上一键恢复完整开发环境
|
||
|
||
### 支持的内容
|
||
|
||
| 类别 | 支持的项目 |
|
||
|------|-----------|
|
||
| 编程语言 | Go, Node.js, Python, Java, Rust, .NET, Ruby, PHP |
|
||
| 包管理器 | Scoop, Chocolatey, Winget, Homebrew, APT |
|
||
| 编辑器 | VS Code (扩展+设置), JetBrains IDEs, Vim/Neovim |
|
||
| Shell | PowerShell, Bash, Zsh, Fish, Windows Terminal |
|
||
| 其他 | Git 配置, 环境变量, SSH 密钥, 字体 |
|
||
|
||
---
|
||
|
||
## 2. 安装
|
||
|
||
### 2.1 通过 Go 安装
|
||
|
||
```bash
|
||
go install github.com/user/devpack@latest
|
||
```
|
||
|
||
### 2.2 通过包管理器安装
|
||
|
||
**Windows (Scoop):**
|
||
```powershell
|
||
scoop bucket add devpack https://github.com/user/devpack-bucket
|
||
scoop install devpack
|
||
```
|
||
|
||
**Windows (Chocolatey):**
|
||
```powershell
|
||
choco install devpack
|
||
```
|
||
|
||
**macOS (Homebrew):**
|
||
```bash
|
||
brew tap user/devpack
|
||
brew install devpack
|
||
```
|
||
|
||
### 2.3 下载二进制文件
|
||
|
||
1. 前往 [GitHub Releases](https://github.com/user/devpack/releases)
|
||
2. 下载对应你系统的压缩包
|
||
3. 解压到一个目录（如 `C:\Tools\devpack\`）
|
||
4. 将该目录添加到系统 PATH
|
||
|
||
### 2.4 验证安装
|
||
|
||
```bash
|
||
devpack version
|
||
```
|
||
|
||
输出示例：
|
||
```
|
||
DevPack v0.1.0 (commit: abc1234, built: 2026-03-03)
|
||
OS: windows/amd64
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 快速入门
|
||
|
||
### 3.1 五分钟上手
|
||
|
||
```bash
|
||
# 第一步：初始化
|
||
devpack init
|
||
|
||
# 第二步：扫描你的环境
|
||
devpack scan
|
||
|
||
# 第三步：打包
|
||
devpack capture --name "my-env"
|
||
|
||
# 第四步：导出为文件（可以拷贝到 U 盘）
|
||
devpack export my-env -o my-env.devpack
|
||
```
|
||
|
||
拿到 `.devpack` 文件后，在新电脑上：
|
||
|
||
```bash
|
||
# 第五步：安装 DevPack 后，导入文件
|
||
devpack import my-env.devpack
|
||
|
||
# 第六步：预览将要做的更改
|
||
devpack restore my-env --dry-run
|
||
|
||
# 第七步：正式还原
|
||
devpack restore my-env
|
||
```
|
||
|
||
### 3.2 推荐工作流
|
||
|
||
```
|
||
旧电脑 新电脑
|
||
────── ──────
|
||
devpack init (安装 DevPack)
|
||
│ │
|
||
devpack scan │
|
||
│ │
|
||
devpack capture --name env │
|
||
│ │
|
||
devpack export env │
|
||
│ │
|
||
└── my-env.devpack ──(U盘)──▶ │
|
||
│
|
||
devpack import my-env.devpack
|
||
│
|
||
devpack restore env --dry-run
|
||
│
|
||
devpack restore env
|
||
│
|
||
✅ 环境就绪！
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 核心概念
|
||
|
||
### 4.1 Pack（环境包）
|
||
|
||
Pack 是 DevPack 生成的打包文件（`.devpack` 格式）。它包含：
|
||
- **Manifest** — 描述包内容的清单
|
||
- **采集器数据** — 各个采集器收集的环境数据
|
||
- **校验信息** — 确保文件完整性
|
||
|
||
一个 Pack 代表某一时刻你的开发环境的"快照"。
|
||
|
||
### 4.2 Profile（配置方案）
|
||
|
||
Profile 定义了"打包什么"和"怎么打包"。通过 Profile，你可以：
|
||
- 只打包特定的工具链（如只打包 Go + VS Code）
|
||
- 排除不需要的内容
|
||
- 为不同场景准备不同的配置方案
|
||
|
||
内置 Profile 模板：
|
||
| 模板 | 包含内容 |
|
||
|------|---------|
|
||
| `minimal` | 只有编辑器设置和 Shell 配置 |
|
||
| `standard` | 运行时 + 编辑器 + Shell + Git + 环境变量 |
|
||
| `full` | 所有可用的采集器 |
|
||
|
||
### 4.3 Collector（采集器）
|
||
|
||
采集器是负责扫描和收集特定类型环境信息的模块。每个采集器独立工作：
|
||
|
||
| 采集器 | 扫描内容 | 还原方式 |
|
||
|--------|---------|---------|
|
||
| `go` | Go 版本、go env、GOPATH/bin 工具 | 下载安装器 |
|
||
| `node` | Node 版本、npm 全局包 | nvm/直接安装 |
|
||
| `python` | Python 版本、pip 全局包 | 安装器/pyenv |
|
||
| `vscode` | 扩展列表、settings.json | code --install-extension |
|
||
| `powershell` | Profile、已安装模块 | 复制 Profile + Install-Module |
|
||
| `scoop` | bucket 列表、已安装包 | scoop install |
|
||
| `git` | .gitconfig、aliases | 复制配置 |
|
||
| `env` | 用户环境变量 | setx/export |
|
||
|
||
### 4.4 还原策略
|
||
|
||
当还原时遇到已存在的配置，DevPack 提供多种处理策略：
|
||
|
||
| 策略 | 行为 |
|
||
|------|------|
|
||
| `skip` | 跳过，保留现有配置 |
|
||
| `overwrite` | 覆盖，使用 Pack 中的配置 |
|
||
| `merge` | 合并两者（适用于配置文件） |
|
||
| `prompt` | 逐项询问用户（默认） |
|
||
| `newest` | 使用较新的版本 |
|
||
|
||
---
|
||
|
||
## 5. 命令详解
|
||
|
||
### 5.1 devpack init
|
||
|
||
初始化 DevPack 配置。
|
||
|
||
```bash
|
||
# 默认初始化
|
||
devpack init
|
||
|
||
# 使用 standard 模板
|
||
devpack init --template standard
|
||
|
||
# 指定 Profile 名称
|
||
devpack init --profile my-profile
|
||
```
|
||
|
||
这会在 `~/.devpack/` 下创建配置目录和默认配置文件。
|
||
|
||
### 5.2 devpack scan
|
||
|
||
扫描当前环境，展示检测到的开发工具和配置。
|
||
|
||
```bash
|
||
# 扫描所有
|
||
devpack scan
|
||
|
||
# 详细模式
|
||
devpack scan --detailed
|
||
|
||
# 只扫描运行时
|
||
devpack scan --category runtime
|
||
|
||
# 只扫描特定采集器
|
||
devpack scan -c go,node,vscode
|
||
|
||
# 输出为 JSON
|
||
devpack scan -o json
|
||
|
||
# 保存扫描结果
|
||
devpack scan --save my-scan.json
|
||
```
|
||
|
||
### 5.3 devpack capture
|
||
|
||
捕获环境数据并创建 Pack。
|
||
|
||
```bash
|
||
# 基本用法
|
||
devpack capture --name "my-env"
|
||
|
||
# 使用 Profile
|
||
devpack capture --name "go-env" --profile golang-dev
|
||
|
||
# 捕获所有
|
||
devpack capture --name "full-env" --all
|
||
|
||
# 只捕获特定采集器
|
||
devpack capture --name "editor-env" -c vscode,git
|
||
|
||
# 带描述和标签
|
||
devpack capture --name "v1" \
|
||
--description "生产环境工具链" \
|
||
--tag golang,production
|
||
```
|
||
|
||
### 5.4 devpack restore
|
||
|
||
从 Pack 还原环境。
|
||
|
||
```bash
|
||
# 先预览
|
||
devpack restore my-env --dry-run
|
||
|
||
# 执行还原
|
||
devpack restore my-env
|
||
|
||
# 跳过冲突项
|
||
devpack restore my-env --conflict skip
|
||
|
||
# 覆盖所有冲突
|
||
devpack restore my-env --conflict overwrite
|
||
|
||
# 只还原特定采集器
|
||
devpack restore my-env -c vscode,git
|
||
|
||
# 跳过确认
|
||
devpack restore my-env -y
|
||
```
|
||
|
||
### 5.5 devpack export / import
|
||
|
||
```bash
|
||
# 导出为文件
|
||
devpack export my-env -o ~/Desktop/my-env.devpack
|
||
|
||
# 导入文件
|
||
devpack import ~/Desktop/my-env.devpack
|
||
|
||
# 导入并指定名称
|
||
devpack import ~/Desktop/my-env.devpack --name imported-env
|
||
|
||
# 导入前验证
|
||
devpack import ~/Desktop/my-env.devpack --verify
|
||
```
|
||
|
||
### 5.6 devpack diff
|
||
|
||
对比环境差异。
|
||
|
||
```bash
|
||
# 与当前环境对比
|
||
devpack diff my-env --current
|
||
|
||
# 两个 Pack 对比
|
||
devpack diff old-env --with new-env
|
||
|
||
# 只对比特定采集器
|
||
devpack diff my-env --current -c runtime
|
||
```
|
||
|
||
### 5.7 devpack list
|
||
|
||
```bash
|
||
# 列出所有 Pack
|
||
devpack list packs
|
||
|
||
# 列出所有 Profile
|
||
devpack list profiles
|
||
|
||
# 列出所有可用采集器
|
||
devpack list collectors
|
||
|
||
# 详细信息
|
||
devpack list packs --detailed
|
||
```
|
||
|
||
### 5.8 devpack profile
|
||
|
||
```bash
|
||
# 创建 Profile
|
||
devpack profile create my-profile
|
||
|
||
# 查看 Profile
|
||
devpack profile show my-profile
|
||
|
||
# 编辑 Profile（使用默认编辑器打开）
|
||
devpack profile edit my-profile
|
||
|
||
# 设置默认 Profile
|
||
devpack profile use my-profile
|
||
|
||
# 删除 Profile
|
||
devpack profile delete my-profile
|
||
|
||
# 列出所有 Profile
|
||
devpack profile list
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 使用场景
|
||
|
||
### 6.1 个人换电脑
|
||
|
||
**场景：** 你买了一台新笔记本电脑，需要迁移开发环境。
|
||
|
||
**步骤：**
|
||
|
||
在旧电脑上：
|
||
```bash
|
||
devpack init
|
||
devpack scan --detailed # 确认要迁移的内容
|
||
devpack capture --name "laptop-2026" --all
|
||
devpack export laptop-2026 -o laptop-2026.devpack
|
||
```
|
||
|
||
将 `laptop-2026.devpack` 拷贝到 U 盘或通过网络传到新电脑。
|
||
|
||
在新电脑上：
|
||
```bash
|
||
# 先安装 DevPack
|
||
devpack import laptop-2026.devpack
|
||
devpack restore laptop-2026 --dry-run # 预览
|
||
devpack restore laptop-2026 # 开始还原
|
||
```
|
||
|
||
### 6.2 团队环境统一
|
||
|
||
**场景：** 你是 Tech Lead，需要为团队准备统一的开发环境。
|
||
|
||
**步骤：**
|
||
|
||
1. 创建团队 Profile：
|
||
```bash
|
||
devpack profile create team-standard
|
||
devpack profile edit team-standard
|
||
```
|
||
|
||
2. 在 Profile 中定义标准配置（编辑 YAML 文件）
|
||
|
||
3. 使用 Profile 打包：
|
||
```bash
|
||
devpack capture --name "team-env-v1" --profile team-standard
|
||
devpack export team-env-v1 -o team-env-v1.devpack
|
||
```
|
||
|
||
4. 分发给团队成员
|
||
|
||
5. 成员还原：
|
||
```bash
|
||
devpack import team-env-v1.devpack
|
||
devpack restore team-env-v1
|
||
```
|
||
|
||
### 6.3 项目环境隔离
|
||
|
||
**场景：** 你同时参与 Go 和 Python 项目，需要不同的环境配置。
|
||
|
||
**步骤：**
|
||
|
||
1. 为每个项目创建 Profile：
|
||
```bash
|
||
devpack profile create golang-project
|
||
devpack profile create python-ml
|
||
```
|
||
|
||
2. 分别配置各 Profile 只包含对应工具链
|
||
|
||
3. 按项目打包：
|
||
```bash
|
||
devpack capture --name "go-env" --profile golang-project
|
||
devpack capture --name "ml-env" --profile python-ml
|
||
```
|
||
|
||
### 6.4 环境排障
|
||
|
||
**场景：** 同事说"在我电脑上能跑"，你需要对比环境差异。
|
||
|
||
```bash
|
||
# 让同事导出环境
|
||
# (同事) devpack capture --name "alice-env" && devpack export alice-env
|
||
|
||
# 你导入并对比
|
||
devpack import alice-env.devpack
|
||
devpack diff alice-env --current
|
||
```
|
||
|
||
差异输出会清晰展示两个环境的不同之处。
|
||
|
||
---
|
||
|
||
## 7. 配置文件
|
||
|
||
### 7.1 配置文件位置
|
||
|
||
| 文件 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| 全局配置 | `~/.devpack/config.yaml` | DevPack 全局设置 |
|
||
| Profile | `~/.devpack/profiles/<name>.yaml` | 命名配置方案 |
|
||
| 日志 | `~/.devpack/logs/devpack.log` | 运行日志 |
|
||
| Pack 存储 | `~/.devpack/packs/` | 本地 Pack 存储 |
|
||
|
||
### 7.2 自定义配置示例
|
||
|
||
```yaml
|
||
# ~/.devpack/config.yaml
|
||
|
||
defaults:
|
||
profile: "standard"
|
||
compression: "gzip"
|
||
conflict_strategy: "prompt"
|
||
|
||
logging:
|
||
level: "info"
|
||
|
||
ui:
|
||
color: true
|
||
progress_bar: true
|
||
|
||
security:
|
||
scan_for_secrets: true
|
||
exclude_patterns:
|
||
- "*_KEY"
|
||
- "*_SECRET"
|
||
- "*_TOKEN"
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 常见问题
|
||
|
||
### Q: DevPack 和 Docker 有什么区别？
|
||
|
||
Docker 用于打包**应用运行环境**，应用运行在容器中；DevPack 用于打包**开发者的本地开发环境**，直接还原到宿主机。两者是互补关系。
|
||
|
||
### Q: 支持跨操作系统迁移吗？
|
||
|
||
不支持。DevPack 只支持同一操作系统之间的迁移（Windows → Windows, macOS → macOS）。不同操作系统的工具链和配置差异太大，无法可靠地自动转换。
|
||
|
||
### Q: 还原会覆盖我现有的配置吗？
|
||
|
||
默认不会。DevPack 使用 `prompt` 策略，遇到冲突会询问你如何处理。你也可以先使用 `--dry-run` 预览所有更改。
|
||
|
||
### Q: Pack 文件大小一般多大？
|
||
|
||
典型的开发环境 Pack 大小在 5-50 MB 之间。Pack 文件只包含配置信息和元数据，不包含实际的安装程序二进制文件（还原时会从网络下载）。
|
||
|
||
### Q: 密码和密钥安全吗？
|
||
|
||
DevPack 默认不采集 SSH 密钥和密码。如果你选择采集 SSH 密钥，它们会使用 AES-256-GCM 加密存储。DevPack 不会采集浏览器密码、系统凭证等隐私数据。
|
||
|
||
### Q: 还原需要网络连接吗？
|
||
|
||
是的。还原过程需要从网络下载对应版本的安装程序。Pack 文件只包含"安装什么"的信息，不包含安装程序本身。
|
||
|
||
### Q: 还原失败了怎么办？
|
||
|
||
如果开启了还原点功能（默认开启），可以使用 `devpack rollback` 撤销所有更改，回到还原前的状态。
|
||
|
||
---
|
||
|
||
## 9. 故障排除
|
||
|
||
### 9.1 查看详细日志
|
||
|
||
```bash
|
||
# 开启详细输出
|
||
devpack scan --verbose
|
||
|
||
# 开启 debug 日志
|
||
devpack scan --log-level debug
|
||
|
||
# 查看日志文件
|
||
# Windows
|
||
notepad %USERPROFILE%\.devpack\logs\devpack.log
|
||
# macOS/Linux
|
||
cat ~/.devpack/logs/devpack.log
|
||
```
|
||
|
||
### 9.2 常见错误
|
||
|
||
| 错误 | 原因 | 解决方案 |
|
||
|------|------|---------|
|
||
| `collector not available` | 对应的工具未安装 | 安装对应工具或排除该采集器 |
|
||
| `pack file corrupted` | Pack 文件损坏 | 使用 `devpack verify` 检查，重新导出 |
|
||
| `platform mismatch` | Pack 的系统与当前不一致 | 只能在相同 OS 之间还原 |
|
||
| `permission denied` | 权限不足 | 以管理员身份运行 |
|
||
| `network timeout` | 下载超时 | 检查网络，或设置代理 |
|
||
|
||
### 9.3 报告问题
|
||
|
||
如果遇到无法解决的问题：
|
||
|
||
1. 运行 `devpack scan --log-level debug --save debug-info.json`
|
||
2. 查看 `~/.devpack/logs/devpack.log`
|
||
3. 在 [GitHub Issues](https://github.com/user/devpack/issues) 创建 Issue
|
||
4. 附上 debug 日志（注意删除敏感信息）
|