macOS 本地 AI 编程环境终极安装手册（2026）

我有满天星辰

177人浏览 · 2026-07-14 21:04:58

我有满天星辰 · 2026-07-14 21:04:58 发布

适用目标：在 macOS 上搭建一套尽量本地、低成本、可读写项目和执行命令的 AI 编程环境。
推荐组合：VS Code + OpenCode + Ollama + Qwen3-Coder + MCP + Java 21 + Maven + Node.js + Vue 3 + Docker Desktop
本手册以 Apple Silicon（M1/M2/M3/M4/M5） 为主，同时标注 Intel Mac 差异。

0. 最终架构

VS Code
├── Java / Vue 项目代码
├── Git
└── 集成终端
      │
      ▼
OpenCode（本地编程 Agent）
├── 读取和修改代码
├── 执行终端命令
├── 调用 MCP 工具
└── 调用 Ollama API
      │
      ▼
Ollama
└── Qwen3-Coder 30B（本地模型）

安装完成后的验收标准

以下命令均能正常输出版本或结果：

brew --version
git --version
java -version
mvn -version
node --version
npm --version
code --version
docker --version
docker compose version
ollama --version
ollama list
opencode --version

第一部分：安装前检查

1.1 检查 macOS 版本

点击：

左上角苹果菜单 → 关于本机

也可执行：

sw_vers

建议使用 macOS 14 Sonoma 或更新版本。Ollama 当前 macOS 版本也要求 macOS 14 或更高。

截图检查点 01

应看到类似：

ProductName:            macOS
ProductVersion:         15.x 或 26.x
BuildVersion:           ...

1.2 检查芯片类型

uname -m

结果说明：

arm64   = Apple Silicon
x86_64  = Intel Mac

也可执行：

system_profiler SPHardwareDataType | grep -E "Chip|Processor|Memory"

内存与模型建议

Mac 内存	建议
8GB	不建议运行 Qwen3-Coder 30B，可先使用小模型或云端模型
16GB	30B 很可能内存不足；建议较小的工具调用模型
24GB	可尝试 30B，但上下文和速度会受限
32GB	可运行 Qwen3-Coder 30B，建议关闭其他大型应用
48GB+	更适合 30B + 64K 上下文
64GB+	本地 Agent 体验更稳定

Qwen3-Coder 30B 的 Ollama 模型文件约 19GB，但运行时还需要上下文缓存、系统和其他程序占用的内存。

1.3 检查磁盘空间

df -h /

建议至少预留：

基础开发工具：15～25GB
Docker 镜像与容器：20GB+
Qwen3-Coder 30B：约 19GB 模型文件
模型运行和缓存：额外预留 20GB+
推荐总剩余空间：80GB 以上

第二部分：安装 Xcode Command Line Tools

Homebrew、Git 和部分编译工具依赖它。

xcode-select --install

系统会弹出安装窗口，点击“安装”。

安装完成后验证：

xcode-select -p

正常结果：

/Library/Developer/CommandLineTools

再验证：

clang --version
git --version

常见错误：`xcode-select: error`

重置路径：

sudo xcode-select --reset

若仍失败：

sudo rm -rf /Library/Developer/CommandLineTools
xcode-select --install

第三部分：安装 Homebrew

3.1 执行官方安装命令

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

安装过程中会显示即将修改的目录，并要求按回车确认。

Homebrew 默认位置：

Apple Silicon：/opt/homebrew
Intel Mac：/usr/local

3.2 配置 Homebrew 到 PATH

安装脚本结束时会给出 Next steps。优先复制它显示的命令。

Apple Silicon 通常执行：

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

Intel Mac 通常执行：

echo 'eval "$(/usr/local/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/usr/local/bin/brew shellenv)"

验证：

brew --version
brew doctor

截图检查点 02

brew --version 应输出 Homebrew 版本；brew doctor 理想结果为：

Your system is ready to brew.

少量警告不一定影响使用，但应阅读提示。

常见错误：`zsh: command not found: brew`

Apple Silicon：

eval "$(/opt/homebrew/bin/brew shellenv)"
source ~/.zprofile

Intel：

eval "$(/usr/local/bin/brew shellenv)"
source ~/.zprofile

第四部分：安装基础开发工具

brew update
brew install git wget curl jq tree

验证：

git --version
jq --version
tree --version

建议配置 Git：

git config --global user.name "你的名字"
git config --global user.email "你的邮箱"
git config --global init.defaultBranch main

查看配置：

git config --global --list

第五部分：安装 VS Code

5.1 使用 Homebrew 安装

brew install --cask visual-studio-code

启动：

open -a "Visual Studio Code"

5.2 安装 `code` 命令

在 VS Code 中按：

Command + Shift + P

搜索并执行：

Shell Command: Install 'code' command in PATH

关闭并重新打开终端，验证：

code --version

打开当前目录：

code .

5.3 推荐扩展

在 VS Code 扩展面板安装：

Extension Pack for Java
Spring Boot Extension Pack
Vue - Official
ESLint
Prettier - Code formatter
Docker
GitLens（可选）

不要同时安装旧版 Volar 和多个相互冲突的 Vue 语言扩展；Vue 3 优先使用 Vue - Official。

第六部分：安装 Java 21 和 Maven

6.1 安装 OpenJDK 21

brew install openjdk@21

Homebrew 的 openjdk@21 是 keg-only，需要创建系统 JDK 链接：

sudo ln -sfn "$(brew --prefix openjdk@21)/libexec/openjdk.jdk" \
  /Library/Java/JavaVirtualMachines/openjdk-21.jdk

添加环境变量：

cat >> ~/.zshrc <<'EOF'

# Java 21
export JAVA_HOME=$(/usr/libexec/java_home -v 21)
export PATH="$JAVA_HOME/bin:$PATH"
EOF

重新加载：

source ~/.zshrc

验证：

java -version
javac -version
echo "$JAVA_HOME"

截图检查点 03

应看到 Java 主版本为 21。

6.2 安装 Maven

brew install maven

验证：

mvn -version

输出中应同时显示：

Apache Maven ...
Java version: 21...

常见错误：Maven 使用了错误 Java

检查全部 JDK：

/usr/libexec/java_home -V

临时切换：

export JAVA_HOME=$(/usr/libexec/java_home -v 21)

永久配置则检查 ~/.zshrc 中是否有其他 JAVA_HOME 覆盖了 Java 21。

第七部分：安装 Node.js、npm 和 Vue 3

7.1 推荐使用 nvm 管理 Node

与直接 brew install node 相比，nvm 更适合项目间切换 Node 版本。

brew install nvm
mkdir -p ~/.nvm

写入配置：

cat >> ~/.zshrc <<'EOF'

# nvm
export NVM_DIR="$HOME/.nvm"
[ -s "$(brew --prefix nvm)/nvm.sh" ] && \. "$(brew --prefix nvm)/nvm.sh"
[ -s "$(brew --prefix nvm)/etc/bash_completion.d/nvm" ] && \. "$(brew --prefix nvm)/etc/bash_completion.d/nvm"
EOF

重新加载：

source ~/.zshrc

安装当前 LTS：

nvm install --lts
nvm use --lts
nvm alias default 'lts/*'

验证：

node --version
npm --version
nvm current

7.2 创建 Vue 3 测试项目

cd ~/Developer
npm create vue@latest vue-local-test

建议选择：

TypeScript：Yes
JSX：No
Vue Router：Yes
Pinia：Yes
Vitest：Yes
E2E：按需
ESLint：Yes
Prettier：Yes

进入并启动：

cd vue-local-test
npm install
npm run dev

终端会显示本地地址，通常为：

http://localhost:5173

浏览器打开后应看到 Vue 欢迎页。

停止服务：

Control + C

第八部分：安装 Docker Desktop

8.1 安装

brew install --cask docker

启动：

open -a Docker

第一次启动需要：

接受 Docker Desktop 使用条款。
选择推荐设置。
输入 macOS 管理员密码。
等待菜单栏 Docker 图标显示运行正常。

Apple Silicon 可选安装 Rosetta 2，以提高少数 amd64 工具兼容性：

softwareupdate --install-rosetta --agree-to-license

8.2 验证

docker --version
docker compose version
docker info

运行测试容器：

docker run --rm hello-world

截图检查点 04

终端应出现：

Hello from Docker!

8.3 推荐资源设置

Docker Desktop：

Settings → Resources

建议：

Mac 内存	Docker 内存
16GB	4GB
24GB	6GB
32GB	8GB
48GB+	8～12GB

本地大模型和 Docker 会争夺统一内存。运行 Qwen3-Coder 时，不要给 Docker 分配过多内存。

常见错误：Cannot connect to Docker daemon

先确认 Docker Desktop 已启动：

open -a Docker

等待图标稳定后：

docker info

架构不匹配

Apple Silicon 遇到仅提供 amd64 的镜像时：

docker run --platform linux/amd64 镜像名

但模拟运行通常更慢，应优先选择 arm64/multi-arch 镜像。

第九部分：安装 Ollama

9.1 推荐安装方式

官方推荐 macOS 用户安装 Ollama 应用。也可通过 Homebrew：

brew install --cask ollama

启动：

open -a Ollama

验证：

ollama --version
curl http://localhost:11434/api/tags

正常情况下，API 返回 JSON。

macOS 应用启动后会在后台管理 Ollama 服务，通常不需要另开终端运行 ollama serve。

常见错误：`ollama: command not found`

重新启动终端，或检查：

which ollama
ls -l /usr/local/bin/ollama

也可直接重新打开 Ollama 应用，让它创建 CLI 链接。

常见错误：端口 11434 被占用

lsof -nP -iTCP:11434 -sTCP:LISTEN

若已有 Ollama 进程，这是正常情况。不要再重复执行 ollama serve。

第十部分：下载 Qwen3-Coder

10.1 当前推荐本地型号

ollama pull qwen3-coder:30b

查看：

ollama list

运行测试：

ollama run qwen3-coder:30b

输入：

请用 Java 21 写一个带方法注释的线程安全单例，并解释实现。

退出：

/bye

10.2 关于模型大小

当前 Ollama 中 qwen3-coder:30b 文件约 19GB，支持较长上下文和工具调用。

不要执行本地 480B 版本，除非机器拥有约 250GB 或更多统一内存：

# 普通 Mac 不要使用
ollama run qwen3-coder:480b

10.3 设置 64K 上下文

OpenCode 官方要求本地模型使用至少 64K 上下文。Ollama 在低内存设备上可能默认仅给 4K 或 32K，因此必须检查和调整。

方式 A：临时启动服务

先完全退出菜单栏 Ollama，再执行：

OLLAMA_CONTEXT_LENGTH=65536 ollama serve

保持此终端运行。

方式 B：创建专用模型

创建文件：

mkdir -p ~/.ollama/modelfiles
cat > ~/.ollama/modelfiles/qwen3-coder-64k.Modelfile <<'EOF'
FROM qwen3-coder:30b
PARAMETER num_ctx 65536
EOF

创建模型：

ollama create qwen3-coder-64k \
  -f ~/.ollama/modelfiles/qwen3-coder-64k.Modelfile

测试：

ollama run qwen3-coder-64k

64K 会显著增加内存占用。若系统频繁使用交换空间或卡死，可先降到 32768 测试；但 OpenCode 的完整 Agent 工作流仍推荐 64K 以上。

查看内存压力：

活动监视器 → 内存 → 内存压力

截图检查点 05

应确认：

ollama list

中存在：

qwen3-coder:30b
qwen3-coder-64k

第十一部分：安装 OpenCode

11.1 推荐官方安装脚本

curl -fsSL https://opencode.ai/install | bash

也可以使用 Homebrew：

brew install anomalyco/tap/opencode

验证：

opencode --version

若提示找不到命令，重新打开终端并检查：

echo "$PATH"
which opencode

第十二部分：连接 OpenCode 与 Ollama

12.1 最简单方式

确保 Ollama 正在运行，然后：

ollama launch opencode

仅生成配置、不直接进入交互界面：

ollama launch opencode --config

12.2 手动配置

创建配置目录：

mkdir -p ~/.config/opencode

创建配置文件：

cat > ~/.config/opencode/opencode.json <<'EOF'
{
  "$schema": "https://opencode.ai/config.json",
  "model": "ollama/qwen3-coder-64k",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "qwen3-coder-64k": {
          "name": "Qwen3-Coder 30B 64K"
        }
      }
    }
  }
}
EOF

验证 JSON：

jq . ~/.config/opencode/opencode.json

12.3 在项目中运行

cd ~/Developer/MindNest
opencode

在 OpenCode 中可输入：

先只分析项目结构，不修改任何文件。列出后端、前端、配置、数据库和测试模块。

再输入：

检查项目能否构建。执行必要的只读检查命令，先不要修改代码。

模型选择命令：

/models

截图检查点 06

应看到 OpenCode 终端界面、当前项目路径，以及 Ollama 的本地模型。

第十三部分：配置 MCP

13.1 MCP 的作用

MCP 让 Agent 能调用外部工具和数据源。OpenCode 自带文件读取、修改和终端执行能力，因此不要无脑安装大量 MCP。

推荐起步只启用：

Context7：查询最新技术文档
Playwright：浏览器自动化和页面测试（按需）
GitHub：访问远程仓库、Issue、PR（按需，通常需要令牌）

Filesystem、Git 等能力若 OpenCode 内置工具已经满足，就没有必要重复添加。MCP 越多，占用的上下文越大。

13.2 添加 Context7 远程 MCP 示例

编辑：

nano ~/.config/opencode/opencode.json

在根对象中加入 mcp。完整示例：

{
  "$schema": "https://opencode.ai/config.json",
  "model": "ollama/qwen3-coder-64k",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "qwen3-coder-64k": {
          "name": "Qwen3-Coder 30B 64K"
        }
      }
    }
  },
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp",
      "enabled": true
    }
  }
}

验证：

jq . ~/.config/opencode/opencode.json

重新启动 OpenCode。

13.3 本地 MCP 通用格式

{
  "mcp": {
    "my-server": {
      "type": "local",
      "command": ["npx", "-y", "某个-mcp-包"],
      "enabled": true,
      "environment": {
        "EXAMPLE_TOKEN": "{env:EXAMPLE_TOKEN}"
      }
    }
  }
}

密钥不要直接写入 Git 仓库。可写到 shell 环境：

export EXAMPLE_TOKEN="你的令牌"

13.4 MCP 安全原则

只使用官方或可信发布者维护的 MCP。
安装前检查源代码、权限和包名。
不向未知 MCP 提供 GitHub、数据库或云平台高权限令牌。
数据库 MCP 优先使用只读账号。
不要让 Agent 自动执行生产环境操作。
每增加一个 MCP，都要评估上下文消耗。

第十四部分：让 VS Code 与 OpenCode 配合

最稳定的方式是使用 VS Code 集成终端：

cd ~/Developer/MindNest
code .

在 VS Code 中打开终端：

Control + `

执行：

opencode

这样可以同时：

左侧：项目文件
中间：代码编辑器
下方：OpenCode Agent
右侧或浏览器：运行结果

推荐工作流：

先让 Agent 分析，不立即修改。
让它列出修改计划。
每次只做一个小功能。
修改后执行测试。
查看 git diff。
人工确认后再提交。

常用命令：

git status
git diff
git diff --staged

第十五部分：MindNest 项目推荐启动方式

假设目录为：

MindNest/
├── backend/
└── frontend/

15.1 后端

cd ~/Developer/MindNest/backend
mvn clean test
mvn spring-boot:run

15.2 前端

新开终端：

cd ~/Developer/MindNest/frontend
npm install
npm run dev

15.3 OpenCode

再开一个 VS Code 终端：

cd ~/Developer/MindNest
opencode

首条提示词建议：

你正在协助开发 MindNest，这是一个 Java 后端 + Vue 前端项目。
先读取项目结构和现有规范，不修改文件。
后续生成的代码必须包含清晰注释，每个新增或修改的方法都必须包含方法注释。
执行命令前说明目的；修改后运行相关测试，并总结改动文件。

可将项目规则写入仓库内的 AGENTS.md：

# MindNest Agent Rules

- 后端使用 Java 21。
- 前端使用 Vue 3。
- 所有新增代码必须包含必要注释。
- 每个新增或修改的方法必须包含清晰的方法注释。
- 修改前先说明计划。
- 每次改动保持小而可验证。
- 修改后运行相关测试。
- 不得提交密钥、令牌、`.env` 或生产配置。
- 未经明确要求，不执行删除数据库、强制推送或破坏性命令。

第十六部分：一键环境检查脚本

创建脚本：

cat > ~/check-local-ai-dev.sh <<'EOF'
#!/usr/bin/env bash

set -u

check_command() {
  local command_name="$1"
  if command -v "$command_name" >/dev/null 2>&1; then
    echo "✅ $command_name: $(command -v "$command_name")"
  else
    echo "❌ $command_name 未安装或不在 PATH"
  fi
}

echo "===== macOS ====="
sw_vers
echo
echo "架构: $(uname -m)"
echo

echo "===== 命令检查 ====="
for command_name in brew git java javac mvn node npm code docker ollama opencode jq; do
  check_command "$command_name"
done

echo
echo "===== Java ====="
java -version 2>&1 | head -n 3 || true

echo
echo "===== Node ====="
node --version 2>/dev/null || true
npm --version 2>/dev/null || true

echo
echo "===== Docker ====="
docker info >/dev/null 2>&1 \
  && echo "✅ Docker daemon 正常" \
  || echo "❌ Docker daemon 未运行"

echo
echo "===== Ollama ====="
curl -fsS http://localhost:11434/api/tags >/dev/null 2>&1 \
  && echo "✅ Ollama API 正常" \
  || echo "❌ Ollama API 无法访问"

echo
echo "===== Ollama 模型 ====="
ollama list 2>/dev/null || true

echo
echo "===== OpenCode 配置 ====="
if [ -f "$HOME/.config/opencode/opencode.json" ]; then
  jq . "$HOME/.config/opencode/opencode.json" >/dev/null 2>&1 \
    && echo "✅ OpenCode JSON 配置有效" \
    || echo "❌ OpenCode JSON 配置无效"
else
  echo "⚠️ 尚未找到 OpenCode 全局配置"
fi
EOF

chmod +x ~/check-local-ai-dev.sh
~/check-local-ai-dev.sh

第十七部分：常见故障排查

17.1 下载速度慢或连接失败

先检查网络：

curl -I https://github.com
curl -I https://ollama.com

不要随意运行来源不明的国内镜像脚本。可使用可信代理，但应在终端中正确设置：

export HTTPS_PROXY=http://127.0.0.1:你的端口
export HTTP_PROXY=http://127.0.0.1:你的端口

取消：

unset HTTPS_PROXY HTTP_PROXY

17.2 `opencode` 无法连接 Ollama

检查服务：

curl http://localhost:11434/api/tags

检查 OpenAI 兼容接口：

curl http://localhost:11434/v1/models

检查模型：

ollama list

检查配置：

jq . ~/.config/opencode/opencode.json

确认 URL 是：

http://localhost:11434/v1

17.3 OpenCode 提示上下文太小

创建 64K 专用模型：

cat > /tmp/Modelfile <<'EOF'
FROM qwen3-coder:30b
PARAMETER num_ctx 65536
EOF

ollama create qwen3-coder-64k -f /tmp/Modelfile

然后在 OpenCode 中使用：

ollama/qwen3-coder-64k

17.4 模型非常慢

检查：

活动监视器 → 内存

重点看：

内存压力
交换使用量
Ollama 内存占用

处理顺序：

关闭 Docker 中不使用的容器。
关闭浏览器的大量标签页。
关闭其他本地模型。
降低上下文长度。
换较小模型。
避免一次加载整个大型仓库。

查看 Docker：

docker ps
docker stats

停止不需要的容器：

docker stop 容器ID

17.5 OpenCode 修改范围过大

使用更明确的提示：

只修改 backend/src/main/java/.../ExampleService.java。
不要修改其他文件。
先给出计划，等计划完成后再实施。
改动后只运行与该类相关的测试。

并始终查看：

git status
git diff

17.6 清理 OpenCode 缓存

遇到 provider 包异常时：

rm -rf ~/.cache/opencode

然后重新启动 OpenCode。

17.7 清理 Ollama 模型

查看：

ollama list

删除不需要的模型：

ollama rm 模型名

模型目录通常占用大量磁盘，删除前确认名称。

17.8 Docker 占用磁盘太大

查看：

docker system df

谨慎清理未使用资源：

docker system prune

删除所有未使用镜像会更激进：

docker system prune -a

执行前必须确认没有需要保留的镜像和缓存。

第十八部分：更新与维护

建议每两周执行：

brew update
brew upgrade
brew cleanup

更新 Ollama 模型：

ollama pull qwen3-coder:30b

更新 npm：

npm install -g npm@latest

检查过期包：

brew outdated
npm outdated

Docker Desktop 和 VS Code 可使用应用内更新。

第十九部分：卸载方法

OpenCode

Homebrew 安装：

brew uninstall opencode

脚本安装则先检查：

which opencode

再按实际路径移除。配置目录：

rm -rf ~/.config/opencode
rm -rf ~/.cache/opencode

Ollama 模型

ollama list
ollama rm qwen3-coder:30b
ollama rm qwen3-coder-64k

卸载应用：

brew uninstall --cask ollama

Docker Desktop

brew uninstall --cask docker

Docker 数据清理需谨慎，避免误删项目数据。

第二十部分：最终验收

依次执行：

brew --version
git --version
java -version
mvn -version
node --version
npm --version
code --version
docker run --rm hello-world
ollama list
curl http://localhost:11434/v1/models
opencode --version

进入 MindNest：

cd ~/Developer/MindNest
opencode

输入：

只读分析当前仓库，告诉我：
1. Java 和 Vue 的版本；
2. 后端与前端的启动命令；
3. 数据库配置位置；
4. 当前测试覆盖情况；
5. 三个最优先处理的工程问题。
不要修改任何文件。

Agent 能正确读取项目、调用本地模型并输出分析，即表示核心环境搭建成功。

官方资料

Homebrew：https://brew.sh/
Homebrew 安装文档：https://docs.brew.sh/Installation
VS Code：https://code.visualstudio.com/
OpenJDK：https://openjdk.org/
Vue：https://vuejs.org/guide/quick-start
Docker Desktop：https://docs.docker.com/desktop/setup/install/mac-install/
Ollama macOS：https://docs.ollama.com/macos
Qwen3-Coder：https://ollama.com/library/qwen3-coder
Ollama + OpenCode：https://docs.ollama.com/integrations/opencode
OpenCode：https://opencode.ai/
OpenCode MCP：https://opencode.ai/docs/mcp-servers/
MCP：https://modelcontextprotocol.io/

DeepSeek技术社区

欢迎加入DeepSeek 技术社区。在这里，你可以找到志同道合的朋友，共同探索AI技术的奥秘。

更多推荐

AI时代，为什么你的网站应该先让AI看懂，而不仅仅是让人看见？

本文探讨了AI搜索工具兴起对网站优化的新要求。随着ChatGPT等AI搜索成为主流，传统的SEO策略已不足以应对新趋势，AI更关注结构化数据而非关键词排名。文章指出，未来网站需要提供清晰的服务信息（如营业时间、预约方式、支付选项等）以便AI理解和推荐。相比传统网站仅作为展示平台，现代网站需要整合从搜索到支付的全流程功能。对于本地服务行业，AI将改变用户的搜索方式，更倾向于直接询问具体需求。作者推荐

DeepSeek技术社区

国内调用 Claude API：中转站选型的 10 个注意事项

国内开发者调用 Claude API 的需求在 2026 年明显增长，市面上中转站数量快速扩张，质量参差不齐。本文整理 10 个常见的选型注意点，从协议透传到跑路风险逐一解读，帮你减少踩坑，并以 jiekou.vip 在各维度上的表现作为参照。

DeepSeek技术社区

基于Qwen3-VL服装大模型QLoRA微调工业落地实践

DeepSeek技术社区

所有评论(0)

查看更多评论

我有满天星辰

@beiluoL

已为社区贡献1条内容

macOS 本地 AI 编程环境终极安装手册（2026）

我有满天星辰

0. 最终架构

安装完成后的验收标准

第一部分：安装前检查

1.1 检查 macOS 版本

截图检查点 01

1.2 检查芯片类型

内存与模型建议

1.3 检查磁盘空间

第二部分：安装 Xcode Command Line Tools

常见错误：xcode-select: error

第三部分：安装 Homebrew

3.1 执行官方安装命令

3.2 配置 Homebrew 到 PATH

截图检查点 02

常见错误：zsh: command not found: brew

第四部分：安装基础开发工具

第五部分：安装 VS Code

5.1 使用 Homebrew 安装

5.2 安装 code 命令

5.3 推荐扩展

第六部分：安装 Java 21 和 Maven

6.1 安装 OpenJDK 21

截图检查点 03

6.2 安装 Maven

常见错误：Maven 使用了错误 Java

第七部分：安装 Node.js、npm 和 Vue 3

7.1 推荐使用 nvm 管理 Node

7.2 创建 Vue 3 测试项目

第八部分：安装 Docker Desktop

8.1 安装

8.2 验证

截图检查点 04

8.3 推荐资源设置

常见错误：Cannot connect to Docker daemon

架构不匹配

第九部分：安装 Ollama

9.1 推荐安装方式

常见错误：ollama: command not found

常见错误：端口 11434 被占用

第十部分：下载 Qwen3-Coder

10.1 当前推荐本地型号

10.2 关于模型大小

10.3 设置 64K 上下文

方式 A：临时启动服务

方式 B：创建专用模型

截图检查点 05

第十一部分：安装 OpenCode

11.1 推荐官方安装脚本

第十二部分：连接 OpenCode 与 Ollama

12.1 最简单方式

12.2 手动配置

12.3 在项目中运行

截图检查点 06

第十三部分：配置 MCP

13.1 MCP 的作用

13.2 添加 Context7 远程 MCP 示例

13.3 本地 MCP 通用格式

13.4 MCP 安全原则

第十四部分：让 VS Code 与 OpenCode 配合

第十五部分：MindNest 项目推荐启动方式

15.1 后端

15.2 前端

15.3 OpenCode

第十六部分：一键环境检查脚本

第十七部分：常见故障排查

17.1 下载速度慢或连接失败

17.2 opencode 无法连接 Ollama

17.3 OpenCode 提示上下文太小

17.4 模型非常慢

17.5 OpenCode 修改范围过大

17.6 清理 OpenCode 缓存

17.7 清理 Ollama 模型

17.8 Docker 占用磁盘太大

第十八部分：更新与维护

第十九部分：卸载方法

OpenCode

Ollama 模型

Docker Desktop

常见错误：`xcode-select: error`

常见错误：`zsh: command not found: brew`

5.2 安装 `code` 命令

常见错误：`ollama: command not found`

17.2 `opencode` 无法连接 Ollama