docs: recommend exec for non-interactive environments

Author: aooohan

docs/guides/faq.md

@@ -11,6 +11,21 @@ that means you do not hook `vfox` into your shell, please hook it manually first
 
 Please refer to [Quick Start#_2-hook-vfox-to-your-shell](./quick-start.md#_2-hook-vfox-to-your-shell) to manually hook `vfox` into your shell.
 
+## How should I use vfox in Docker, CI/CD, or other non-interactive shells?
+
+Prefer `vfox exec`.
+
+`vfox activate` works by installing shell hooks, which are intended for interactive shells. In Docker build steps, CI jobs, and other non-interactive shells, these hooks are usually not triggered automatically.
+
+Recommended examples:
+
+```bash
+vfox exec nodejs@24.14.0 -- npm install -g pnpm
+vfox exec nodejs@24.14.0 -- bash -lc 'node -v && npm -v'
+```
+
+Use `vfox use` when you want to persist version selection for Global, Project, or Session scope. Use `vfox exec` when you want a command to run immediately with the correct SDK environment.
+
 ## Why can't I select when use `use` and `search` commands in GitBash?
 
 Related ISSUE: [Unable to select in GitBash](https://github.com/version-fox/vfox/issues/98)

docs/usage/core-commands.md

@@ -224,6 +224,19 @@ The `exec` command allows you to temporarily execute commands in a specified SDK
 - **Script Execution**: Use specific SDK versions in CI/CD or build scripts
 - **Temporary Testing**: Test code with different SDK versions
 
+::: tip Non-Interactive Environments
+
+For Docker, CI/CD, and other non-interactive shells, prefer `vfox exec` instead of relying on `vfox activate`.
+
+`activate` integrates vfox through shell hooks, while `exec` prepares the SDK environment explicitly for the subprocess you are running.
+
+```shell
+vfox exec nodejs@24.14.0 -- npm install -g pnpm
+vfox exec nodejs@24.14.0 -- bash -lc 'node -v && npm -v'
+```
+
+:::
+
 **Examples**
 
 ```shell

docs/zh-hans/guides/faq.md

@@ -11,6 +11,21 @@
 
 请按照[快速入门#_2-挂载vfox到你的shell](./quick-start.md#_2-挂载vfox到你的shell)步骤进行手动挂载。
 
+## 在 Docker、CI/CD 或其他非交互 Shell 中应该怎么使用 vfox？
+
+推荐优先使用 `vfox exec`。
+
+`vfox activate` 的工作方式是安装 Shell Hook，这更适合交互式 Shell。在 Docker 构建步骤、CI Job 以及其他非交互 Shell 中，这些 Hook 通常不会自动触发。
+
+推荐示例：
+
+```bash
+vfox exec nodejs@24.14.0 -- npm install -g pnpm
+vfox exec nodejs@24.14.0 -- bash -lc 'node -v && npm -v'
+```
+
+如果你希望把版本选择持久化到 Global、Project 或 Session 作用域，请使用 `vfox use`。如果你希望某条命令立刻在正确的 SDK 环境中执行，请使用 `vfox exec`。
+
 
 ## GitBash下`use`和`search`命令无法进行选择?
 

docs/zh-hans/usage/core-commands.md

@@ -226,6 +226,19 @@ vfox x <sdk-name>[@<version>] -- <command> [args...]
 - **脚本执行**: 在 CI/CD 或构建脚本中使用特定 SDK 版本
 - **临时测试**: 临时使用不同版本的 SDK 测试代码
 
+::: tip 非交互环境
+
+在 Docker、CI/CD 和其他非交互 Shell 中，推荐优先使用 `vfox exec`，而不是依赖 `vfox activate`。
+
+`activate` 通过 Shell Hook 集成 vfox，而 `exec` 会为当前子进程显式准备好 SDK 环境。
+
+```shell
+vfox exec nodejs@24.14.0 -- npm install -g pnpm
+vfox exec nodejs@24.14.0 -- bash -lc 'node -v && npm -v'
+```
+
+:::
+
 **示例**
 
 ```shell