---
name: env-config
description: 环境配置详细指南。当 aide env ensure 检测失败需要配置环境时使用。提供模块选择、配置设置、多项目场景处理等详细指导。
---

# 环境配置指南

当 `aide env ensure` 检测失败（输出 `✗`）时，使用本指南分析项目所需环境并完成配置。

---

## 一、问题诊断

### 1.1 常见失败原因

| 错误信息 | 原因 | 解决方案 |
|----------|------|----------|
| `已启用但缺少配置项: path` | 类型B模块未配置路径 | 使用 `aide env set` 配置 |
| `未知模块: xxx` | 启用了不存在的模块 | 检查模块名拼写 |
| `xxx 未安装` | 工具未安装 | 安装对应工具或移除该模块 |
| `node_modules 不存在` | Node.js 依赖未安装 | 配置 node_deps 模块 |

### 1.2 查看可用模块

```bash
aide env list
```

---

## 二、模块分类

### 2.1 类型A：全局工具检测（无需配置）

| 模块 | 检测内容 |
|------|----------|
| `python` | Python 解释器版本 |
| `uv` | uv 包管理器 |
| `rust` | Rust 工具链（rustc + cargo） |
| `node` | Node.js 运行时 |
| `flutter` | Flutter SDK |
| `android` | Android SDK（ANDROID_HOME） |

### 2.2 类型B：项目级检测（需要配置）

| 模块 | 配置项 | 说明 |
|------|--------|------|
| `venv` | `path` | Python 虚拟环境目录 |
| `requirements` | `path` | Python 依赖文件路径 |
| `node_deps` | `path`, `manager`(可选) | Node.js 项目依赖 |

---

## 三、配置命令

### 3.1 aide env set

```bash
# 设置启用的模块列表
aide env set modules <模块列表>

# 设置模块配置
aide env set <模块名>.<配置项> <值>
```

### 3.2 验证规则

- 设置 `modules` 时，验证每个模块类型是否存在
- 无效模块名会报错并显示可用模块列表

```bash
# 验证失败示例
$ aide env set modules python,fortran
✗ 未知模块: fortran
→ 可用模块: python, uv, venv, requirements, rust, node, flutter, node_deps, android
```

---

## 四、项目类型配置

### 4.1 项目特征与模块映射

| 项目特征 | 推荐模块 |
|----------|----------|
| 存在 `Cargo.toml` | `rust` |
| 存在 `package.json` | `node`, `node_deps` |
| 存在 `pubspec.yaml` | `flutter` |
| 存在 `build.gradle` 或 `android/` | `android` |
| 存在 `requirements.txt` 或 `.venv` | `python`, `uv`, `venv`, `requirements` |

### 4.2 配置示例

**Rust 项目**：
```bash
aide env set modules rust
```

**Node.js 项目**：
```bash
aide env set modules node,node_deps
aide env set node_deps.path .
```

**Flutter 项目**：
```bash
aide env set modules flutter
# 如果需要构建 Android APK
aide env set modules flutter,android
```

**Python 项目**：
```bash
aide env set modules python,uv,venv,requirements
aide env set venv.path .venv
aide env set requirements.path requirements.txt
```

**混合项目**（多种技术栈）：
```bash
aide env set modules rust,node,flutter,android
```

---

## 五、多项目场景

### 5.1 模块实例化命名

当工作目录下有多个同类型子项目时，使用 `模块类型:实例名` 格式：

```bash
# 多个 Node.js 项目
aide env set modules node,node_deps:frontend,node_deps:admin
aide env set node_deps:frontend.path frontend
aide env set node_deps:admin.path admin
```

### 5.2 配置文件格式

```toml
[env]
modules = ["node", "node_deps:frontend", "node_deps:admin"]

[env."node_deps:frontend"]
path = "frontend"

[env."node_deps:admin"]
path = "admin"
manager = "pnpm"
```

### 5.3 输出示例

```
✓ node: 24.11.1 (npm 11.6.2)
✓ node_deps:frontend: frontend (npm)
✓ node_deps:admin: admin (pnpm)
✓ 环境就绪 (...)
```

---

## 六、node_deps 模块详解

### 6.1 配置项

| 配置项 | 必需 | 说明 |
|--------|------|------|
| `path` | 是 | package.json 所在目录 |
| `manager` | 否 | 包管理器，默认自动检测 |

### 6.2 包管理器自动检测

根据锁文件自动判断：

| 锁文件 | 包管理器 |
|--------|----------|
| `pnpm-lock.yaml` | pnpm |
| `yarn.lock` | yarn |
| `bun.lockb` | bun |
| `package-lock.json` 或无 | npm |

### 6.3 ensure 行为

检测失败时自动运行对应的安装命令：
- npm: `npm install`
- pnpm: `pnpm install`
- yarn: `yarn install`
- bun: `bun install`

---

## 七、配置流程

### 7.1 标准流程

```bash
# 1. 查看可用模块
aide env list

# 2. 分析项目类型，设置模块
aide env set modules <根据项目选择>

# 3. 配置类型B模块（如有）
aide env set <模块>.<配置项> <值>

# 4. 验证配置
aide env ensure
```

### 7.2 快速配置模板

**前端项目**：
```bash
aide env set modules node,node_deps
aide env set node_deps.path .
aide env ensure
```

**全栈项目**：
```bash
aide env set modules node,node_deps:frontend,node_deps:backend
aide env set node_deps:frontend.path frontend
aide env set node_deps:backend.path backend
aide env ensure
```

**移动端项目**：
```bash
aide env set modules flutter,android
aide env ensure
```

---

## 八、故障排除

### 8.1 模块检测失败

```bash
# 查看详细信息
aide env ensure --verbose
```

### 8.2 重置配置

直接修改 `.aide/config.toml` 或重新运行：

```bash
aide env set modules <新的模块列表>
```

### 8.3 跳过某个模块

从 modules 列表中移除该模块即可。