MacOS 开发环境开荒标准化配置：用了很多年 Mac 之后，总结记录下来的一些开发环境最佳实践

---

---

如果已经用了几年 Mac 做开发，大概率会经历一个很相似的过程。刚买电脑的时候，环境是干净的。那时候会觉得：“Mac 真省心”。 但随着项目越来越多，技术栈越来越复杂，环境会开始慢慢失控。

今天装一个 Java。明天切一个 Node。后天 Docker 跑不起来。再过几个月，IDEA 和终端的 Git 已经不是同一个版本了。

没有从全局角度出发编排安装的 Mac 开发环境，其实大概率是一直处于一种“能跑但不稳定”的状态。表面上看：

• Java 能启动
• Maven 能打包
• Node 能运行
• IDEA 能打开项目

但真正开发一段时间后，各种问题会慢慢浮现：

• IDEA 和终端使用的 Git 不一致
• Java 8 / 17 / 21 来回切换崩环境
• Node 版本混乱
• npm 权限问题
• Docker 占满内存
• Claude Code / Codex 启动失败
• MCP server 跑不起来
• PATH 越配越乱
• Apple Git 和 Homebrew Git 冲突
• Maven settings 到处复制

最后往往会演变成：“这个 Mac 只能继续将就用了，不敢再动”。
后来慢慢发现：真正麻烦的，从来不是不会安装。而是：“半年以后还能不能维护”。因为开发环境这种东西，一旦失控，后面会越来越不敢动。最后会进入一种奇怪状态：电脑还能开发。但没人知道为什么还能开发。包括自己。

正好今年从 Intel 过渡到新的 Apple Silicon 电脑，我按照我兼顾个人开发和工作开发的实际需求出发，梳理记录了我认为能够易于维护的一套环境搭建指南。这篇文章不仅是软件安装清单。而是一套真正适合长期使用的、面向 2026 年全面拥抱 AI 开发生态的 Mac 开发环境标准化方案。

重点要解决的是：

• 长期稳定易于维护
• 企业、个人开发兼容
• Java + Node 双栈友好
• AI Coding 工具兼容
• 尽量避免 PATH 地狱
• 尽量减少未来迁移成本

适用对象：

• M 系列 MacBook
• Java / Spring Boot / Vue / React 开发者
• 使用 IDEA、VSCode
• 使用 Docker、K8s
• 准备接入 Claude Code / Codex / MCP 的开发者

一、先建立正确的目录体系

很多开发环境从第一步就已经开始混乱了。

比如：

• JDK 放 Downloads
• Maven 放 Desktop
• Node 不知道在哪
• Docker 配置找不到
• 各种 SDK 四处分散

长期维护几乎一定崩。

推荐一开始就统一目录结构。

建议：

~/Tools
~/Workspace
~/Scripts

含义：

~/Tools       所有开发工具
~/Workspace   所有项目代码
~/Scripts     自定义脚本

然后继续细分。

例如：

~/Tools/java
~/Tools/maven
~/Tools/gradle
~/Workspace/company-project
~/Workspace/open-source

不要把开发工具放：

~/ 				# 用户根目录
~/Desktop
~/Downloads

因为这些目录天然带有“临时目录”的气质，用于安装和管理开发环境时间久了必乱。

---

二、Homebrew：Mac 开发环境的基础设施

2026 年的 Mac 开发，Homebrew 基本已经属于基础设施。

先安装 Homebrew：

这里推荐中科大镜像地址的一键安装脚本

/bin/bash -c "$(curl -fsSL https://gitee.com/ineo6/homebrew-install/raw/master/install.sh)"

官网的安装脚本（需要科学上网）：

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

安装完成后执行：

brew doctor

看到：

Your system is ready to brew.

说明环境正常。

如果遇到 command not found brew，请执行下面脚本完成安装或者直接重新打开终端:

eval "$(/opt/homebrew/bin/brew shellenv)"

Apple Silicon（M 芯片）下，Homebrew 默认位置：

/opt/homebrew

这一点后面会非常重要。

---

三、统一 Shell：使用 zsh

现在 macOS 默认 shell 已经是 zsh。

确认：

echo $SHELL

正常应看到：

/bin/zsh

之后所有环境变量统一配置在：

~/.zshrc

很多问题，其实不是技术问题。以前我也经常：

• 哪里报错修哪里
• 缺什么装什么
• PATH 不行就继续 append
• npm 报权限问题就 sudo

短期都能解决。但长期一定会留下隐患。后来越来越发现：真正稳定的环境，往往都很“克制”。

不要：

• 一部分写 .bash_profile
• 一部分写 .zprofile
• 一部分写 .zshenv

否则未来调试 PATH 会非常痛苦。

---

四、建立一份真正可长期维护的 ~/.zshrc

这一部分非常关键。很多人的 PATH 混乱，本质是：

• 配置散乱
• 没有分层
• 没有统一规则

建议按模块组织。先编辑：

open ~/.zshrc

推荐结构：

# ========================
# Base（系统基础）
# ========================
# 作用：定义语言环境，保证终端 / Maven / Git 输出一致
export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8


# ========================
# Homebrew（包管理器入口）
# ========================
# 作用：自动注入 brew 环境路径
# 注意：不要手动再写 /opt/homebrew/bin
eval "$(/opt/homebrew/bin/brew shellenv)"


# ========================
# Java Homes（多版本SDK管理）
# ========================
# 作用：统一通过系统 java_home 获取 JDK 路径
# 扩展方式：
#   1. 新增 JDK：export JAVA_XX_HOME=$(/usr/libexec/java_home -v XX)
#   2. 添加函数：javaXX() { ... }

export JAVA_8_HOME=$(/usr/libexec/java_home -v 1.8)
export JAVA_17_HOME=$(/usr/libexec/java_home -v 17)
export JAVA_21_HOME=$(/usr/libexec/java_home -v 21)

# 默认 Java（修改这里即可改变默认版本）
export JAVA_HOME=$JAVA_8_HOME


# ========================
# PATH Java 清理工具（核心安全机制）
# ========================
# 作用：防止 PATH 中残留旧 Java 路径导致版本“偷跑”
# 注意：只删除 JavaVirtualMachines 相关路径
clean_java_path() {
  export PATH=$(echo "$PATH" \
    | tr ':' '\n' \
    | grep -v "JavaVirtualMachines" \
    | tr '\n' ':' \
    | sed 's/:$//')
}


# ========================
# Java 切换函数（标准入口）
# ========================
# 作用：切换 Java 版本的唯一入口
# 规则：
#   × 不要直接改 PATH
#   ✔ 只改 JAVA_HOME + 重新注入 PATH

java8() {
  export JAVA_HOME=$JAVA_8_HOME
  clean_java_path
  export PATH="$JAVA_HOME/bin:$PATH"
  java -version
}

java17() {
  export JAVA_HOME=$JAVA_17_HOME
  clean_java_path
  export PATH="$JAVA_HOME/bin:$PATH"
  java -version
}

java21() {
  export JAVA_HOME=$JAVA_21_HOME
  clean_java_path
  export PATH="$JAVA_HOME/bin:$PATH"
  java -version
}


# ========================
# Maven（多版本管理）
# ========================
# 作用： 统一通过系统 maven_home 获取 Maven 路径
# 扩展方式：
#   1. 新增版本：MAVEN_XX_HOME
#   2. 新增函数：mavenXX()

export MAVEN_38_HOME="$HOME/Tools/apache-maven-3.8.1"
export MAVEN_HOME="$MAVEN_38_HOME"
export PATH="$MAVEN_HOME/bin:$PATH"


# Maven PATH 清理工具
# 作用：防止多个 Maven 路径叠加
clean_maven_path() {
  export PATH=$(echo "$PATH" \
    | tr ':' '\n' \
    | grep -v "apache-maven" \
    | grep -v "maven" \
    | tr '\n' ':' \
    | sed 's/:$//')
}


# Maven 切换入口
# 规则同 Java：先清理，再注入
m38() {
  export MAVEN_HOME="$MAVEN_38_HOME"
  clean_maven_path
  export PATH="$MAVEN_HOME/bin:$PATH"
  hash -r
  mvn -v
}

}

# ========================
# Maven Settings（多配置文件）
# ========================

# export MAVEN_SETTINGS_COMPANY="$MAVEN_HOME/conf/settings-company.xml"
export MAVEN_SETTINGS_COMPANY="$HOME/.m2/settings-company.xml"

# ========================
# Maven 快捷命令
# ========================

# 使用公司 settings
alias mvnc='mvn -s "$MAVEN_SETTINGS_COMPANY"'

# 跳过测试
alias mvnskip='mvn -Dmaven.test.skip=true -Ddockerfile.skip=true'
alias mvncskip='mvnc -Dmaven.test.skip=true -Ddockerfile.skip=true'

# 强制更新依赖
alias mvnrefresh='mvnskip -U'
alias mvncrefresh='mvncskip -U'

# Debug 模式
alias mvndebug='mvnskip -X'
alias mvncdebug='mvncskip -X'


# ========================
# Gradle
# ========================
# 作用：单版本工具，无切换逻辑
# 注意：如需多版本，可仿照 Maven/Java 加 clean_gradle_path

export GRADLE_HOME="$HOME/Tools/gradle-8.14"
export PATH="$GRADLE_HOME/bin:$PATH"


# ========================
# Node
# ========================
# 作用：Node 版本管理入口
# 注意：版本切换交给 nvm，不建议写 PATH 切换逻辑

export NVM_DIR="$HOME/.nvm"
[ -s "/opt/homebrew/opt/nvm/nvm.sh" ] && . "/opt/homebrew/opt/nvm/nvm.sh"


# ========================
# pnpm（全局包管理）
# ========================
# 作用：全局 pnpm 命令支持
# 注意：不要重复追加 pnpm PATH

export PNPM_HOME="$HOME/Library/pnpm"
export PATH="$PNPM_HOME:$PATH"


# ========================
# Aliases（快捷命令）
# ========================
# 作用：提升日常操作效率

alias ll='ls -lah'
alias cls='clear'


# ========================
# 扩展指引
# ========================
# 如果你要扩展这套环境，请遵守以下规则：
#
# 1. 新工具（如 Python / Go / Rust）
#    → 只做 PATH 一次性注入
#
# 2. 需要版本切换的工具（Java / Maven）
#    → 必须配：
#       - clean_xxx_path
#       - xxxXX() 切换函数
#
# 3. 禁止在切换函数中无限追加 PATH
#
# 4. PATH 只能“初始化 + 可控重建”，不能累加污染
#
# 5. 优先原则：
#    JAVA_HOME / TOOL_HOME > PATH
#
# ========================

保存后执行：

source ~/.zshrc

这时候你的环境结构已经开始稳定了。

---

五、Git：不要卸载 Apple Git

这是很多人会踩的大坑。

你会看到：

git --version

输出：

git version 2.50.1 (Apple Git-155)

于是有人会想：“我要卸载苹果 Git”。其实不建议。

原因很简单：macOS 的 /usr/bin/git 已经属于系统工具链的一部分。它和：

• Xcode
• Command Line Tools
• 某些系统脚本

都有耦合。

正确做法不是删除。而是：“让新版 Git 优先”。

安装最新版：

brew install git

然后检查：

which git

正常应该：

/opt/homebrew/bin/git

这说明 Homebrew Git 已经优先。

接着配置 Git：

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

推荐额外配置：

git config --global core.longpaths true
git config --global core.quotepath false
git config --global pull.rebase false
git config --global init.defaultBranch main

这些能避免很多中文路径和 rebase 问题。

---

六、SSH：开发运维的核心能力

现在几乎所有 Git 平台都推荐 SSH。

生成 SSH Key：

ssh-keygen -t ed25519 -C "你的邮箱"

一路回车即可。

然后启动 agent：

eval "$(ssh-agent -s)"

加入 key：

ssh-add ~/.ssh/id_ed25519

查看公钥：

cat ~/.ssh/id_ed25519.pub

复制到：

• GitHub
• GitLab
• 企业 Git
• Gitee

测试：

ssh -T git@github.com

如果成功，你后续 clone/pull/push 会舒服很多。

---

七、Java：推荐一种多版本 JDK 管理切换的思路

2026 年很多公司的现状其实很割裂：

• 老系统 Java 8
• 中间系统 Java 17
• 新系统 Java 21

你几乎不可能只装一个版本。

推荐使用 Temurin：

https://adoptium.net

安装：

brew install --cask temurin@8
brew install --cask temurin@17
brew install --cask temurin@21

查看：

/usr/libexec/java_home -V

你会看到多个 JDK。

这时候前面 .zshrc 中的 Java 切换函数就会特别好用。

例如：

java17
# 会自动输出 java -version

将立刻切到 Java 17。

但随着项目越来越多，会开始出现一种很真实的问题：“项目要求的不是 Java 17”。
而是：

必须 Java 17.0.8
或者只能 8u321

这在企业开发里其实特别常见。尤其：

• 老 Spring Boot
• 老 MySQL 驱动
• TLS/SSL
• Docker JVM
• JNI/native library
• 加密算法

很多时候差一个 patch version 就会出问题，Homebrew 更适合安装“主版本”，如果要“锁 patch version”精准控制子版本，引入SDKMAN 会舒服很多。

SDKMAN 是什么

SDKMAN 本质上是：

Java/Kotlin/Gradle 等 SDK 的版本管理器

有点类似：

• nvm 管 Node
• pyenv 管 Python

但它是专门面向 JVM 生态的。

官方：SDKMAN 官方网站

安装：

curl -s "https://get.sdkman.io" | bash

然后：

source "$HOME/.sdkman/bin/sdkman-init.sh"

---

SDKMAN 的切换体验会舒服很多

例如：

sdk use java 17.0.8-tem

当前 shell 立刻切换。

永久默认：

sdk default java 17.0.8-tem

查看当前：

sdk current java

维护成本会低很多，使用姿势也更优雅。

---

八、Maven：在版本错杂的企业项目中寻求稳定的配置方式

很多人直接用 IDEA bundled Maven。短期没问题。长期经常出版本兼容问题。

尤其：

• Java 8
• 老 Spring Boot
• 私服
• 老插件

建议自己安装不同版本的maven以适应不同的开发环境的。

下载：

https://maven.apache.org/download.cgi

推荐：

场景	版本
老企业项目	3.8.1
新项目	3.9.x

很多企业项目其实仍然锁定 3.8.1。

放置位置例如：

~/Tools/apache-maven-3.8.1

配置：

export MAVEN_HOME=/Users/xiekunlin/Tools/apache-maven-3.8.1
export PATH=$MAVEN_HOME/bin:$PATH

验证：

mvn -v

---

九、Maven settings 的正确管理方式

不要把 settings.xml 到处复制。

推荐：

~/.m2/settings.xml

如果有多个环境：

settings-company.xml
settings-test.xml
settings-dev.xml

可以做 alias：

alias mvnj='mvn -s ~/Tools/apache-maven-3.8.1/conf/settings-company.xml'

之后：

mvnj clean package

就会很舒服。

贴一下日常常用的阿里云镜像：

<mirror>
  <id>aliyun</id>
  <mirrorOf>*</mirrorOf>
  <url>https://maven.aliyun.com/repository/public</url>
</mirror>

会明显提升依赖下载速度。

---

十、Gradle：现代 Java 项目越来越重要

现在越来越多：

• Kotlin
• Android
• 新 Spring Boot
• 多模块项目

都偏向 Gradle。

安装：

brew install gradle

验证：

gradle -v

推荐开启：

org.gradle.daemon=true
org.gradle.parallel=true
org.gradle.caching=true

位置：

~/.gradle/gradle.properties

这会明显提升构建速度。

---

十一、Node.js：不要官网直接安装

这是前端环境最容易崩的原因之一。

错误的姿势：

• 官网安装 Node
• 手工升级
• npm 全局安装一堆工具

最后版本冲突严重。

推荐：

使用 nvm 管理。

安装：

brew install nvm

创建目录：

mkdir ~/.nvm

安装 Node：

nvm install 20
nvm install 22

设置默认：

nvm alias default 20

查看：

node -v

这时候你的 Node 环境会稳定很多。

---

十二、pnpm：现代前端开发几乎必备

现在很多：

• monorepo
• Vue3
• AI SDK
• MCP Server

都已经偏向 pnpm。

安装：

npm install -g pnpm

初始化：

pnpm setup

验证：

pnpm -v

pnpm 最大优势：

• 更快
• 更省磁盘
• monorepo 体验更好
• node_modules 不容易炸

---

十三、Docker Desktop：不要默认配置直接用

很多人的 Docker 卡顿，本质是默认配置不合理。

安装：

https://www.docker.com/products/docker-desktop/

打开：

Settings -> Resources

推荐：

配置	建议
CPU	6~8
Memory	8G~16G
Swap	2G

开启：

Use Virtualization Framework
VirtioFS

关闭：

Kubernetes

除非你真的做 K8s。

否则它只会浪费资源。

---

十四、IDEA：很多问题其实是配置问题

IDEA 很吃电脑内存和 CPU 性能。

优化的重点是：“不要让 IDEA 自己乱管理工具链”。

统一配置：

类型	路径
Git	/opt/homebrew/bin/git
Maven	~/Tools/apache-maven-3.8.1
Gradle	Local
JDK	Temurin

不要：

• bundled Maven
• bundled Gradle
• Apple Git

否则终端和 IDEA 的行为会不一致。

推荐插件：

插件	用途
Lombok	Java
MyBatisX	MyBatis
GitToolBox	Git
JRebel and XRebel	热部署
HighlightBracketPair	括号高亮（个人感觉比 Rainbow Brackets 更轻量更高效，Rainbow 主要是好看）
Translation	翻译
Key Promoter X	快捷键

---

十五、Claude Code / Codex：AI Coding 最大的问题不是模型

而是环境。

新手搭建出来的环境总以为是：“AI 不稳定。”

踩过坑之后发现除了网络问题，更多的主要是：

• Node 环境乱
• Git PATH 混用
• npm cache 权限问题
• MCP server 启动失败

统一策略：

类型	推荐
Git	推荐使用 Homebrew 安装较新版本的 Git 即可
Node	nvm 管理 Node 版本
pnpm	一般默认最新即可
Shell	zsh
Python	pyenv（可选）

错误姿势：

• 系统 Node
• Apple Git
• sudo npm install -g

如果不能保证这些工作环境稳定，几乎都是未来问题源头。

开发环境越规范，后续基于 AI Agent 的可玩性会更多样且不会因为环境的坑就先掉头发

---

十六、2026 AI 开发的重要基础设施

随着 2026 年 AI 智能体（Agent）越来越强大，它们不再只是简单的“代码补全工具”，而是可以自主操作终端、调用工具、修改项目文件甚至执行数据库命令的“本地开发代理”。
如果还在用 2025 年的安装教程，那几乎可以肯定，你的 AI 开发环境可能已经落后一到两代了。本文总结了 macOS 下最实用、最安全、最接地气的部署方案和操作经验。

---

1、OpenAI Codex CLI：最具性价比的 AI 编程小帮手

Codex CLI 不只是一个命令行工具，它本质是一个轻量级的 AI agent runtime，能在你本地执行多步任务、自动修改代码，并在隔离的 Git Worktree 中运行，保证不会意外污染主分支。

1.1 架构理解

简单来说，它的执行流程是这样的：

用户目标 → Planner 拆解任务 → Tool Runtime 执行 → Shell/Git/Filesystem → Verifier 校验结果 → 循环优化

意思是：

• 它可以拆分复杂任务，例如“修复前端 bug + 后端 API 接口同步”
• 自动执行命令
• 在临时工作区尝试修改，失败可以回滚
• 所有改动都可在本地控制，不影响主分支

---

1.2 安装方法

🔹 官方 Native Installer（最推荐）

curl -fsSL https://chatgpt.com/codex/install.sh | sh

特点：

• 不依赖 Node.js，避免版本冲突
• 自动更新，稳定性最高
• 与 macOS 权限系统兼容性好

💡 小贴士：如果你之前用 npm 安装过旧版本，先卸载再用 native installer，否则路径会冲突。

---

🔹 Homebrew Cask（适合版本控制）

brew uninstall codex --formula
brew install --cask codex

✅ 优点：便于集中管理和升级，适合团队共享开发环境

---

🔹 npm 全局安装（仅兼容老项目）

npm install -g @openai/codex

⚠️ 注意：

• 不建议长期使用
• 会遇到 PATH 和权限问题
• sudo 安装会搞乱 node_modules 权限
• 如果前面所提及的工具维护得非常规范，用起来还是比较舒服

---

1.3 验证和登录

codex --version
codex login  # 打开浏览器完成授权

💡 小贴士：第一次登录会在默认浏览器打开 ChatGPT 页面，完成 OAuth 授权后 CLI 才能启动 agent loop。

---

1.4 工作区和安全建议

• 创建独立 AI 工作区，例如 ~/Workspace/VibeProjects
• 只授权该目录访问权限，避免 Full Disk Access
• 避免 sudo 安装
• 遇到 macOS Gatekeeper 阻拦：

xattr -d com.apple.quarantine /Applications/Codex.app

---

1.5 AGENTS.md：从规则文件到能力策略

现在 AGENTS.md 不只是写写注释，而是定义了 AI agent 的能力边界：

# 允许命令
npm test
pnpm lint

# 禁止路径
.env
terraform/state
production/

# 审批命令
database migration
git push --force

• 相当于 Kubernetes 的 Policy
• 定义了 AI 能执行哪些操作
• 防止 AI 越界修改敏感文件

---

2、Claude Code：超大上下文智能体

Claude Code 是 Anthropic 的 CLI Agent，能处理超长上下文，非常适合大型项目自动修复、批量重构和多文件任务。

2.1 安装方法

🔹 官方 Native Installer（推荐）

curl -fsSL https://claude.ai/install.sh | bash

🔹 Homebrew Cask

brew install --cask claude-code        # 稳定版
brew install --cask claude-code@latest # 前沿版

🔹 npm 全局安装（仅兼容老环境）

npm install -g @anthropic-ai/claude-code

💡 官方正逐步弱化 npm 安装，因为 native installer 才能提供统一 agent runtime、自动更新和安全沙箱。

---

2.2 验证命令

claude --version
claude doctor   # 自检环境完整性
claude          # 启动 agent loop

2.3 实战小贴士

• 预装 ripgrep，提高大项目索引和搜索速度：

brew install ripgrep

• 免费账号不支持 CLI，必须 Pro / Max / Team / Enterprise

---

3、MCP：AI Agent 的“系统调用协议”

Model Context Protocol（MCP）是 AI Agent 的核心基础设施，它定义了 agent 能调用哪些工具、访问哪些资源，并控制能力边界。

3.1 MCP Runtime 架构

AI Agent
   ↓
MCP Client
   ↓
Transport（stdio/websocket）
   ↓
MCP Server
   ↓
Filesystem / Browser / GitHub / DB

MCP 不再只是“插件协议”，它几乎是 AI 的 syscall layer，让 agent 能安全操作本地和云端资源。

---

3.2 安装和管理

项目级安装（推荐）

pnpm add -D @modelcontextprotocol/sdk

企业级 Dockerized MCP Server

{
  "github": {
    "command": "docker",
    "args": ["run", "--rm", "..."]
  }
}

⚡ 建议不要全局 npm 安装 MCP Server，安全风险太高。

---

3.3 macOS 核心配置文件

Agent	路径	作用
Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json	Claude 的 MCP Tool Registry
Cursor	~/.cursor/mcp.json	Cursor 的 MCP 配置入口
Cline	~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json	Cline 的 Agent Tool Runtime 配置

第一次看到这些 json 文件时，会下意识觉得它们只是“插件配置”。
但实际上，它们更像 AI Agent 的“能力注册中心”。

这些配置真正决定的，不是界面主题或者普通参数，而是：

• AI 能访问哪些目录
• AI 能调用哪些工具
• AI 能不能执行 shell
• AI 能不能连接数据库、GitHub、浏览器

也就是说，这些文件本质上是在给 AI “接线”。
模型本身并不会操作你的电脑，真正让 Claude、Codex、Cursor 具备本地操作能力的，其实是背后的 MCP Runtime 和这些 Tool Registry。

例如下面这段配置：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "~/Workspace/VibeProjects"
      ]
    }
  }
}

真正的含义并不是“启用了一个插件”，而是：

• 启动 filesystem MCP Server
• 向 Agent 注册 read/write/list tools
• 并且把 ~/Workspace/VibeProjects 作为 AI 的能力边界（Capability Boundary）

这意味着：AI 只能访问这里，而不是你的整个 macOS，所以现在越来越多人开始单独创建：~/AIWorkspace，本质上就是在给 AI 创建一个独立 Sandbox Root。

---

3.4 推荐的配置管理结构

当 MCP Server 越来越多后，你会发现 AI Runtime 的复杂度其实已经开始接近一个“小型操作系统”。

比如你可能同时会有：

• filesystem
• github
• postgres
• browser
• docker
• kubernetes
• playwright

如果这些配置散落在各个 json 文件里，后期会非常混乱，甚至容易导致 Agent 权限越界。

更推荐的做法是统一管理：

~/.ai/
├── agents/
│   ├── claude/
│   ├── codex/
│   └── cursor/
│
├── mcp/
│   ├── base/
│   ├── finance/
│   ├── devops/
│   └── experimental/
│
├── policies/
│   ├── readonly.json
│   ├── safe-write.json
│   └── production-deny.json
│
├── runtime/
│   ├── logs/
│   ├── cache/
│   └── sockets/
│
├── workspaces/
│   ├── springboot/
│   ├── vue3/
│   └── k8s/
│
└── secrets/

这样做最大的好处不是“看起来整洁”，而是：

• 不同项目可以拥有不同能力边界
• AI Runtime、日志、缓存、策略可以统一治理
• secrets 不会混进普通配置
• 方便做 Dockerized MCP 隔离
• 后续多人协作、团队治理也更容易

比如：

项目	能力策略
finance	禁止 shell 和数据库写入
k8s	允许 kubectl
vue3	仅允许 filesystem
production	完全只读

到了 2026 年，AI 开发环境已经不再只是“装几个 CLI 工具”，而更像是在本地搭建一个小型 AI Operating System。

---

4、macOS 权限与沙箱治理

AI Agent 最大的风险不是写错代码，而是越界操作系统资源。

• 仅授权 AI 工作目录
• 避免 Full Disk Access
• 配合 Worktree 和 Docker 沙箱
• AGENTS.md 定义能力边界

💡 小贴士：macOS TCC 会拦截 Desktop / Documents / Downloads / Camera / Accessibility / Full Disk Access，需要提前规划权限。

---

十七、我认为重要的几个开发环境习惯

不要轻易：

sudo npm install -g

不要：

• 修改系统 Python
• 多个 Node 混装
• PATH 到处 append

推荐统一工具安装、环境工作根路径：

/opt/homebrew
~/Tools
~/Workspace

推荐统一工具来源、统一 shell、统一 PATH。

你的开发环境会稳定很多。

---

十八、最后的完整验证

执行：

git --version
node -v
npm -v
pnpm -v
java -version
mvn -v
gradle -v
docker -v

如果全部正常。说明你的 Mac 开发环境已经进入一种比较长期稳定的状态。后续无论：Java、Vue、Spring Boot、Docker、AI Coding、MCP 都能比较舒服地扩展。慢慢你会发现，真正舒服的开发环境，不会再害怕升级、不会再害怕重装、不会再害怕切项目。因为整个体系是清晰的。

你知道：

• 工具在哪
• 为什么这么配
• PATH 怎么来的
• 哪些是系统的
• 哪些是自己的
• 出问题应该从哪里查

半年后、一年后、两年后。你依然知道。

这种状态，其实会明显降低开发焦虑。尤其现在 AI Coding 越来越重。Claude Code、Codex、MCP 这些工具，本质上都越来越依赖一个“稳定、干净、可预期”的本地环境。环境越乱，AI Agent 越容易出现各种奇怪问题。