🌟 功能特性
核心能力
- 分支隔离开发
为每个 Git 分支创建独立的 node_modules 环境
- 智能环境切换
自动根据当前分支匹配最佳沙箱（支持精确/模糊匹配）
- 补丁集成系统
自动应用项目 patches 目录下的所有补丁
效率工具
- 可视化状态栏
实时显示当前激活的沙箱环境
- 一键式操作
通过命令面板快速安装/清理沙箱
- 安全清理机制
二次确认 + 自动重试的沙箱删除
开发者友好
- 跨平台支持
完美兼容 Windows/macOS/Linux 系统
- 错误恢复系统
详细错误日志 + 快速重试功能
- 进度可视化
所有耗时操作均显示实时进度
基础使用
创建新沙箱
# 快捷键(Ctrl+Shift+P(Windows)/Cmd+Shift+P(Mac))打开命令面板
# 通过命令面板运行 "Sandbox: Install"
# 输入标识符（推荐分支命名格式：feature-login）
自动切换环境
git checkout -b feature-new
# 插件将自动检测并切换匹配沙箱
清理旧沙箱
# 通过命令面板运行 "Sandbox: Clean"
# 选择要删除的沙箱
🛠 进阶使用
命令参考
| 命令 |
快捷键 |
功能描述 |
Sandbox: Install |
- |
创建新沙箱 |
Sandbox: Clean |
- |
删除现有沙箱 |
Sandbox: AutoSwitch |
- |
手动触发自动切换 |
配置建议
最佳实践
- 分支命名格式：
type-description（示例：feat-user-auth）
- 补丁文件命名：
package-name+version.patch
目录结构
your-project/
│ ├── syf/ # 唯一标识对应的依赖目录
│ │ └── node_modules
│ │ └── package.json
│ │ └── package-lock.json
│ └── jiangyin/
│ └── node_modules
│ │ └── package.json
│ │ └── package-lock.json
├── package.json
└── package-lock.json
└── node_modules -> .node_modules/current/node_modules # 动态符号链接
⚙️ 开发指南
环境要求
- Node.js 16+
- VS Code 1.78+
- Git 2.20+
📚 最佳实践
分支管理策略
- 长期维护分支（main/dev）使用基础沙箱
- 功能分支使用
feat-前缀
- 修复分支使用
fix-前缀
补丁管理
- 将修改后的.patch 文件放入 patches 目录
- 每次新建沙箱时会自动应用
- 推荐使用官方 patch-package 生成补丁
⚠️ 注意事项
必要前提
- 项目必须包含 package.json
- Windows 系统需启用开发者模式（符号链接支持）
- 自动切换功能需在 Git 仓库中使用
常见问题
Q：node_modules 显示异常？
A：尝试以下步骤：
- 执行
Sandbox: Clean
- 重新
Sandbox: Install
- 重启 VS Code
Q：补丁未生效？
A：检查：
- patches 目录结构是否正确
- 补丁文件名格式是否符合要求
- 目标包版本是否匹配
工作流程
- Fork 仓库
- 创建特性分支 (
git checkout -b feat/awesome)
- 提交修改 (
git commit -m 'Add feature')
- 推送到分支 (
git push origin feat/awesome)
- 创建 Pull Request
代码规范
- TypeScript 严格模式
- 所有异步操作必须包含错误处理
- 用户交互需提供取消选项
- 重要操作需包含进度提示
| |
