🎉 What's Changed in v1.x #603
Description
🎉 What's Changed in v1.x
🎉 Core Improvement: Solving the Temporary Directory Problem
Problem Background
Prior to v1.x, regardless of whether using session, global, or project scope, all SDKs would be stored in temporary directories. This caused the previously configured version information to become invalid immediately when the shell was closed, resulting in "directory not found" errors in virtual environments and CI/CD workflows.
v1.x Solution
This version completely separates the behavior of the three scopes, adopting a more rational management strategy:
📍 Project Scope (Project-level)
- Automatically generates
.vfox/sdks/<sdk>symlinks in the current project directory - Adds the project path to PATH for project isolation
- Optional parameter:
--unlinkto disable this behavior (not recommended) - Recommendation: Add the generated
.vfox/directory to.gitignore
⏱️ Session Scope (Session-level)
- Maintains original behavior, SDKs stored in temporary directories
- Bound to shell lifecycle, automatically cleaned up when shell closes
🌍 Global Scope (Global)
- Generates permanent symlinks under
~/.vfox/sdks/<sdk> - Points to actual SDK version directories
- Remains effective across shell sessions
Priority Rules
Priority is controlled by the PATH environment variable, from highest to lowest as follows:
#Project > Session > Global > System
$PWD/.vfox/sdks/nodejs/bin:~/.vfox/tmp/<pid>/nodejs/bin:~/.vfox/sdks/nodejs/bin:/usr/bin:...For detailed usage, please refer to documentation
Additional Features
New Configuration Format Support
- Introduces
vfox.tomland.vfox.tomlnew configuration formats for a clearer configuration experience - Fully backward compatible with legacy
.tool-versionsformat for smooth migration
Multi-user Support
- Support for multi-user scenarios with independent configuration spaces for each user
- Global configuration and SDK installation support, simplifying unified management in team environments
Exec Command
- New
execcommand allows executing arbitrary commands with specified SDK versions - Seamlessly integrates with CI/CD pipelines and VSCode
- Usage example:
vfox x nodejs@20 -- node -v
🎉 核心改进：解决临时目录问题
问题背景
在 v1.x 之前，无论使用 session、global 还是 project 作用域，所有 SDK 都会存储在临时目录中。这导致当 shell 关闭后，之前配置的版本信息立即失效，造成虚拟环境和 CI 流程中出现"目录不存在"的错误。
v1.x 方案
本版本将三个作用域的行为彻底拆分，采用更加合理的管理策略：
📍 Project 作用域（项目级）
- 在当前项目目录下自动生成
.vfox/sdks/<sdk>软链 - 将项目路径加入 PATH，实现项目隔离
- 可选参数：
--unlink禁用此行为（不推荐） - 建议：将生成的
.vfox/目录添加到.gitignore
⏱️ Session 作用域（会话级）
- 保持原有行为，SDK 存储在临时目录中
- 与 shell 生命周期绑定，关闭 shell 自动清理
🌍 Global 作用域（全局）
- 在
~/.vfox/sdks/<sdk>下生成永久软链 - 指向实际的 SDK 版本目录
- 跨 shell 会话保持有效
优先级规则
通过 PATH 环境变量控制优先级，从高到低依次为：
#Project > Session > Global > System
$PWD/.vfox/sdks/nodejs/bin:~/.vfox/tmp/<pid>/nodejs/bin:~/.vfox/sdks/nodejs/bin:/usr/bin:...具体用法请参考文档
其他功能
新配置格式支持
- 引入
vfox.toml和.vfox.toml新配置格式，提供更清晰的配置体验 - 完全兼容旧版
.tool-versions格式，确保平滑迁移
多用户支持
- 支持多用户场景，每个用户拥有独立配置空间
- 支持全局配置和 SDK 安装，便于团队环境统一管理
Exec 命令
- 新增
exec命令，允许在指定 SDK 版本下执行任意命令 - 完美支持 CI/CD 流程和 VSCode 集成
- 用法示例：
vfox x nodejs@20 -- node -v