三亩地 三亩地SAN MU DI · CODE DIARY
交流投稿
ARTICLE DETAIL

日记详情

真实记录编程学习的某一天，欢迎挑你感兴趣的翻一翻。

首页/学习日记/日记详情

Mac开发环境搭建全攻略：从Homebrew到ASDF的工程化实践

发布时间：2026/8/5 5:30:52 三亩地 编程学习日记
Mac开发环境搭建全攻略：从Homebrew到ASDF的工程化实践

1. 项目概述：为什么Mac开发环境搭建值得一聊

最近身边好几个朋友从Windows换到了Mac，第一件事就是问我：“这玩意儿开发环境怎么搞？” 这让我想起自己刚接触Mac时，也是一头雾水。从Windows那种“下一步、下一步、完成”的安装逻辑，切换到Mac的Unix-like命令行生态，确实需要一个适应过程。但一旦搭建完成，那种丝滑、稳定、高效的体验，会让你觉得之前的折腾都是值得的。今天，我就以一个过来人的身份，把一次完整的Mac开发环境搭建过程掰开揉碎了讲清楚，从系统基础配置到核心开发工具链，再到环境管理与优化，目标是让你拿到一台新Mac后，能快速进入高效编码状态，而不是在搜索引擎和报错信息里反复横跳。

这篇文章适合所有在Mac上进行开发的工程师，无论你是前端、后端、移动端还是嵌入式开发者。我会重点覆盖通用基础环境（如Homebrew、Shell、Git）、主流语言环境（如Python、Java、Node.js）以及IDE/编辑器（如VSCode）的配置，并穿插大量我踩过的坑和总结的技巧。整个过程追求的是“可复现”和“知其所以然”，不仅告诉你点哪里，更告诉你为什么这么做。

2. 核心思路与工具选型：构建可持续维护的环境

搭建开发环境，最忌讳的就是东一榔头西一棒子，从各种官网下载pkg安装包，最后导致环境混乱、依赖冲突。我的核心思路是：以包管理器为中心，实现环境隔离，并通过配置文件进行版本控制。这样既能保证环境纯净，也便于在新机器上快速复现。

2.1 基石之选：为什么一定是Homebrew？

在Mac上，Homebrew是当之无愧的“标配”包管理器。你可以把它理解为Mac上的“软件中心”，但它更强大，专注于开发工具和命令行程序。它的优势在于：

  1. 依赖管理自动化：安装一个软件，它会自动帮你解决所有依赖库，不用手动折腾。
  2. 集中化安装：所有通过Homebrew安装的软件都集中在/usr/local/Cellar（Intel芯片）或/opt/homebrew（Apple Silicon芯片）目录下，结构清晰，易于管理。
  3. 强大的社区（Cask）：除了命令行工具，Homebrew Cask可以让你用命令一键安装图形化应用（如Chrome、VSCode），彻底告别手动下载dmg文件。
  4. 易于更新和卸载：一行命令就能更新所有软件，卸载也干净彻底。

注意：如果你的Mac是M1/M2/M3等Apple Silicon芯片，请务必使用ARM原生版本的Homebrew，它安装在/opt/homebrew路径下，与Intel版本的/usr/local隔离，能获得最佳性能和兼容性。

2.2 Shell环境：Zsh + Oh My Zsh 的黄金组合

Mac自Catalina系统起，将默认Shell从Bash换成了Zsh。Zsh功能更强大，但默认配置比较朴素。Oh My Zsh是一个社区驱动的Zsh配置管理框架，它集成了大量实用的插件、主题和便捷功能，能极大提升终端的使用体验和效率。

选择它的理由：

  • 主题丰富：轻松更换终端外观，显示Git分支、时间、电池等信息一目了然。
  • 插件生态：例如git插件提供大量Git命令别名（如gst代表git status），zsh-autosuggestions能根据历史记录自动提示命令。
  • 统一管理：所有配置通过~/.zshrc一个文件管理，备份和迁移极其方便。

2.3 版本控制与多版本管理：ASDF的降维打击

开发中经常需要切换不同版本的编程语言运行时（如Node.js的16.x, 18.x, 20.x）。以前我们需要分别安装nvm、rbenv、pyenv等工具来管理不同语言。现在，我强烈推荐使用ASDF。

ASDF是一个通用的版本管理工具，通过插件体系，可以管理几乎所有主流编程语言的版本（Ruby, Node.js, Python, Java, Go, Elixir等）。它的好处是：

  • 一个工具，全部搞定：无需记忆不同工具的命令（nvm use,rbenv local），ASDF使用统一的asdf install,asdf local命令。
  • 项目级版本锁定：通过在项目根目录创建.tool-versions文件，可以指定该项目使用的语言版本，进入目录后自动切换，完美解决多项目版本冲突问题。
  • 与Shell无缝集成：安装后自动在Shell中注入切换逻辑。

3. 基础环境搭建实操全记录

接下来，我们进入实战环节。请打开你的“终端”应用，我们一步步来。

3.1 第一步：安装Homebrew

首先，我们需要安装这个一切的基石。打开终端，粘贴以下命令：

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

这个命令会从Homebrew的官方GitHub仓库下载安装脚本并执行。安装过程中，脚本会提示你安装Xcode Command Line Tools（这是编译软件必须的），按照提示确认即可。

安装后重要配置（Apple Silicon芯片必做）： 对于M系列芯片的Mac，安装完成后，终端会给出几条提示命令，你需要执行它们将Homebrew添加到环境变量中。通常类似这样：

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

第一行命令将配置写入你的Zsh配置文件（~/.zshrc），第二行是立即生效。执行后，可以运行brew --version来验证安装成功。

3.2 第二步：配置终极终端环境（Zsh + Oh My Zsh）

  1. 确认默认Shell为Zsh：通常新系统已是Zsh，可通过echo $SHELL查看。
  2. 安装Oh My Zsh：
    sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"
    安装过程会备份你原有的~/.zshrc文件。
  3. 配置主题和插件：编辑~/.zshrc文件。
    nano ~/.zshrc
    • 修改主题：找到ZSH_THEME行，推荐使用agnoster或robbyrussell（默认）。agnoster功能强大但需要安装特殊字体，新手可先用robbyrussell。
    • 启用插件：找到plugins=(git)这一行，添加你需要的插件。例如：
      plugins=(git zsh-autosuggestions zsh-syntax-highlighting)
      zsh-autosuggestions（命令建议）和zsh-syntax-highlighting（语法高亮）需要额外安装：
      brew install zsh-autosuggestions zsh-syntax-highlighting
      安装后，还需在~/.zshrc文件末尾添加source语句（Oh My Zsh安装脚本有时不会自动添加）：
      source /opt/homebrew/share/zsh-autosuggestions/zsh-autosuggestions.zsh source /opt/homebrew/share/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh
      （Intel芯片路径为/usr/local/share）
  4. 生效配置：
    source ~/.zshrc
    现在你的终端应该焕然一新，并且有命令自动提示和彩色高亮了。

3.3 第三步：安装并配置ASDF

  1. 使用Homebrew安装ASDF：
    brew install asdf
  2. 将ASDF集成到Shell：在~/.zshrc文件末尾添加以下行（如果Homebrew安装后已自动添加，则无需重复）：
    echo -e "\n. $(brew --prefix asdf)/libexec/asdf.sh" >> ~/.zshrc source ~/.zshrc
  3. 添加语言插件：比如我们需要管理Node.js和Python。
    # 添加Node.js插件 asdf plugin-add nodejs https://github.com/asdf-vm/asdf-nodejs.git # 添加Python插件 asdf plugin-add python
  4. 安装特定版本语言：
    # 列出所有可安装的Node.js版本 asdf list-all nodejs # 安装最新的LTS版本（例如18.x） asdf install nodejs lts # 设置为全局默认版本 asdf global nodejs lts # 验证 node --version npm --version
    Python的安装类似，但Python编译时间较长，需要耐心等待。

实操心得：使用ASDF安装Python时，务必确保系统已安装完整的Xcode Command Line Tools和Homebrew的依赖包readline和sqlite，否则可能编译失败。可以提前运行brew install readline sqlite3。

4. 核心开发工具链安装与配置

基础环境就绪后，我们来安装具体的开发工具。

4.1 版本控制：Git

虽然系统可能自带Git，但版本通常较旧。建议用Homebrew安装并配置最新版。

brew install git

配置你的用户信息，这是提交代码时的身份标识：

git config --global user.name "你的名字" git config --global user.email "你的邮箱" git config --global init.defaultBranch main # 设置默认分支为main

一个提升效率的配置：为Git命令设置全局别名。编辑~/.gitconfig或在终端执行：

git config --global alias.st status git config --global alias.co checkout git config --global alias.br branch git config --global alias.ci commit

之后，你就可以用git st代替git status了。

4.2 全能编辑器：Visual Studio Code

使用Homebrew Cask安装，这是最干净的方式：

brew install --cask visual-studio-code

关键配置与插件推荐： 安装后，你可以在终端使用code命令直接打开项目或文件。首次启动VSCode，我建议配置以下核心设置（通过Cmd+,打开设置，点击右上角“打开设置(JSON)”）：

{ "editor.fontSize": 14, "editor.tabSize": 2, "editor.insertSpaces": true, "editor.renderWhitespace": "all", "files.autoSave": "afterDelay", "terminal.integrated.fontSize": 13, "workbench.colorTheme": "Default Dark Modern", "[python]": { "editor.formatOnSave": true } }

必装插件清单：

  • Python(Microsoft): Python语言支持，包含IntelliSense、调试等。
  • Pylance(Microsoft): Python的语言服务器，提供超强的代码补全和类型检查。这里回答一个热词问题：不安装Python解释器只装Pylance行吗？不行。Pylance是“增强补全引擎”，它需要依赖一个具体的Python解释器（环境）来分析你的代码库和第三方库。没有Python解释器，VSCode连基本的语法识别和代码运行都做不到。
  • Java Extension Pack(Microsoft): Java开发全家桶。
  • ESLint: JavaScript/TypeScript代码检查。
  • Prettier: 代码格式化工具。
  • GitLens: 超级强大的Git历史查看工具。
  • Remote - SSH(Microsoft): 远程开发神器。

4.3 数据库：MySQL/PostgreSQL

根据你的需求选择，同样用Homebrew安装。

安装MySQL：

brew install mysql brew services start mysql # 启动并设置为开机自启 mysql_secure_installation # 运行安全初始化脚本，设置root密码等

安装PostgreSQL：

brew install postgresql brew services start postgresql

PostgreSQL安装后默认创建一个与当前系统用户同名的数据库超级用户，无需密码即可通过psql命令登录。

注意事项：Homebrew安装的服务，其数据文件、配置文件通常都在/opt/homebrew/var/mysql或/opt/homebrew/var/postgresql目录下。卸载前记得备份。管理服务常用命令：brew services list（查看）、brew services restart mysql（重启）。

4.4 容器化：Docker Desktop

对于现代开发，Docker几乎是必需品。前往Docker官网下载Docker Desktop for Mac的Apple Silicon或Intel版本安装包进行安装。安装后，需要启动Docker Desktop应用，并在状态栏看到鲸鱼图标运行，才能在终端使用docker和docker-compose命令。

配置镜像加速：国内拉取镜像慢，可以在Docker Desktop的Preferences -> Docker Engine中，添加国内镜像加速器地址：

{ "registry-mirrors": [ "https://hub-mirror.c.163.com", "https://mirror.baidubce.com" ] }

5. 特定语言环境深度配置

5.1 Python环境最佳实践

虽然用ASDF安装了Python，但Python生态中项目依赖隔离至关重要。这里推荐使用pipenv或poetry。

使用Pipenv：

  1. 全局安装Pipenv：pip install pipenv（请确保你使用的pip对应ASDF管理的Python版本）。
  2. 进入你的项目目录：cd my_project
  3. 创建虚拟环境并安装依赖：pipenv install requests
  4. 激活虚拟环境：pipenv shell
  5. Pipenv会自动生成Pipfile和Pipfile.lock来管理依赖。

使用Poetry（更现代）：

  1. 使用Homebrew安装：brew install poetry
  2. 新建项目：poetry new my_project
  3. 添加依赖：cd my_project && poetry add requests
  4. 激活虚拟环境：poetry shell
  5. Poetry使用pyproject.toml和poetry.lock管理依赖。

核心技巧：在VSCode中，你需要为每个项目选择正确的Python解释器。按下Cmd+Shift+P，输入“Python: Select Interpreter”，选择对应虚拟环境下的Python路径（通常位于~/.local/share/virtualenvs/或项目目录/.venv/下）。这样代码分析、调试和运行才会基于正确的环境。

5.2 Java环境（JDK）配置

使用ASDF安装和管理多个JDK版本非常方便。

  1. 添加Java插件：asdf plugin-add java
  2. 列出所有可安装版本：asdf list-all java
  3. 安装特定版本（如AdoptOpenJDK 11）：asdf install java adoptopenjdk-11.0.16+8
  4. 设置全局版本：asdf global java adoptopenjdk-11.0.16+8
  5. 验证：java -version

关于热词“mac安装jdk8”：如果你确实需要老版本的JDK 8，可以在ASDF的列表中找到类似adoptopenjdk-8.0.352+8的版本进行安装。强烈不建议直接从Oracle官网下载pkg安装，那样会污染系统路径，且难以管理多个版本。

5.3 Node.js与前端环境

ASDF已经管理了Node.js。在此基础上，前端开发还有两个常用工具：

  1. Yarn / pnpm (包管理器)：Node.js自带npm，但Yarn和pnpm在速度和确定性方面更有优势。可以在全局安装其一：
    npm install -g yarn pnpm
  2. npx：这是npm 5.2+自带的工具，用于直接运行远程或本地的npm包二进制文件，无需全局安装（如npx create-react-app my-app）。

项目级实践：在项目根目录，使用asdf local nodejs lts命令，会创建.tool-versions文件锁定Node.js版本。然后使用yarn init或npm init创建项目，依赖会被记录在package.json中。

6. 进阶配置与效率提升

6.1 终端复用器：tmux

当你需要长时间运行任务（如开发服务器），或者在一个窗口中管理多个终端会话时，tmux是神器。它允许你在一个终端窗口内创建多个“窗格”（Pane）和“会话”（Session），即使关闭终端窗口，任务仍在后台运行。

安装与基础使用：

brew install tmux # 启动一个新会话 tmux # 在会话内，常用快捷键（需先按前缀键 Ctrl+b，然后按）： # % 垂直分割窗格 # " 水平分割窗格 # 方向键 切换窗格 # d 分离会话（让会话在后台运行） # 重新连接会话 tmux attach

6.2 SSH密钥管理与GitHub/GitLab配置

安全的代码推送离不开SSH密钥。

  1. 生成密钥对：
    ssh-keygen -t ed25519 -C "your_email@example.com"
    一路回车，使用默认路径（~/.ssh/id_ed25519）。
  2. 将公钥添加到Git服务商：
    cat ~/.ssh/id_ed25519.pub
    复制输出的内容，登录GitHub或GitLab，在Settings -> SSH and GPG keys中添加。
  3. 测试连接：
    ssh -T git@github.com
    看到欢迎信息即表示成功。

6.3 环境变量管理

将敏感信息（如API密钥）或常用路径存储在环境变量中是良好实践。推荐在~/.zshrc文件末尾添加，或者创建单独的配置文件如~/.zshenv。

# 在 ~/.zshrc 中添加 export PATH="$HOME/.local/bin:$PATH" # 添加自定义脚本路径 export EDITOR="code -w" # 设置默认编辑器为VSCode # 敏感信息可以放在 ~/.zshenv 中，并设置文件权限为600

7. 常见问题与故障排查实录

即使按照步骤，也可能遇到问题。这里记录几个高频问题。

7.1 Homebrew安装或更新极慢/失败

原因：Homebrew的软件源（Formula）和二进制包（Bottles）默认仓库在国外。

解决方案：更换国内镜像源。

  1. 替换Homebrew核心源：
    cd "$(brew --repo)" git remote set-url origin https://mirrors.ustc.edu.cn/brew.git
  2. 替换Homebrew Bottles源（关键）：在~/.zshrc中添加（针对bash shell则是~/.bash_profile）：
    # 对于Apple Silicon Mac export HOMEBREW_BOTTLE_DOMAIN=https://mirrors.ustc.edu.cn/homebrew-bottles/bottles # 对于Intel Mac # export HOMEBREW_BOTTLE_DOMAIN=https://mirrors.ustc.edu.cn/homebrew-bottles
    然后执行source ~/.zshrc。
  3. 替换Homebrew Cask源（用于图形应用）：
    cd "$(brew --repo)/Library/Taps/homebrew/homebrew-cask" git remote set-url origin https://mirrors.ustc.edu.cn/homebrew-cask.git
    注意：Cask镜像有时不完整，如果安装失败，可以暂时切回官方源git remote set-url origin https://github.com/Homebrew/homebrew-cask。

7.2 终端提示“zsh: command not found: xxx”

可能原因及解决：

  1. 软件未安装：用brew list检查是否已安装。
  2. PATH环境变量问题：这是最常见原因。新安装的软件路径未加入PATH。
    • 对于Homebrew安装的软件，通常不需要手动加PATH，除非是自定义安装。
    • 检查echo $PATH，看是否包含/opt/homebrew/bin（Apple Silicon）或/usr/local/bin（Intel）。
    • 确保~/.zshrc中正确配置了Homebrew环境（见3.1节）。
  3. Shell配置未生效：执行source ~/.zshrc。

7.3 VSCode终端或命令无法使用code命令

原因：VSCode的code命令未添加到PATH。

解决：

  1. 打开VSCode。
  2. 按下Cmd+Shift+P，输入 “shell command”。
  3. 选择 “Shell Command: Install ‘code’ command in PATH”。
  4. 重启终端即可。

7.4 Python虚拟环境在VSCode中不生效

现象：在终端里激活了虚拟环境，但VSCode的终端或运行代码时仍使用系统Python。

解决：

  1. 确保在项目目录下激活了虚拟环境（如pipenv shell或poetry shell）。
  2. 在VSCode中，按下Cmd+Shift+P，选择“Python: Select Interpreter”，从列表中选择虚拟环境下的Python路径。
  3. 更一劳永逸的方法：在项目根目录创建一个.vscode/settings.json文件，内容如下：
    { "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python" }
    （假设你的虚拟环境目录是.venv）。这样每次打开这个项目，VSCode都会自动使用指定的解释器。

7.5 端口被占用问题

开发时经常遇到“Address already in use”错误。

快速排查：

# 查看哪个进程占用了8080端口 lsof -i :8080 # 或者使用更简洁的命令 sudo lsof -i :8080

命令会列出进程ID（PID）。然后可以使用kill -9 <PID>结束该进程。

一个更友好的别名：在~/.zshrc中添加：

alias killport='function _killport(){ lsof -ti:$1 | xargs kill -9; };_killport'

之后，要杀占用8080端口的进程，只需killport 8080。

8. 环境备份与迁移：你的配置也是资产

辛辛苦苦配好的环境，换电脑怎么办？学会备份和迁移是关键。

  1. 备份Homebrew已安装软件列表：

    brew bundle dump --file=~/Desktop/Brewfile --force

    这会在桌面生成一个Brewfile文件，记录了所有通过Homebrew安装的软件和Cask应用。

  2. 备份ASDF已安装工具列表：

    asdf list > ~/Desktop/asdf_plugins.txt

    同时，你的~/.tool-versions文件本身就记录了各项目的版本。

  3. 备份Shell配置：整个~/.zshrc文件，以及~/.oh-my-zsh/custom/目录下的自定义配置。

  4. 备份VSCode配置与插件：

    • 设置和快捷键：通过VSCode的“设置同步”功能登录账号同步。
    • 手动备份：插件列表可以通过code --list-extensions > ~/Desktop/vscode_extensions.txt导出。用户设置文件在~/Library/Application Support/Code/User/目录下。

在新机器上恢复：

  1. 安装Homebrew和Oh My Zsh。
  2. 通过brew bundle install --file=~/Desktop/Brewfile一键恢复所有软件。
  3. 安装ASDF，并根据asdf_plugins.txt安装插件和对应版本。
  4. 复制~/.zshrc等配置文件。
  5. 安装VSCode，通过cat ~/Desktop/vscode_extensions.txt | xargs -L 1 code --install-extension批量安装插件。

经过以上步骤，你应该得到了一台高度定制化、高效且易于维护的Mac开发机器。这套环境的优势在于，它建立在包管理器和配置文件的基石上，具有可重复性和可追溯性。最大的体会是，前期花时间建立一套科学的配置和管理流程，后期会节省无数排查环境问题的时间，让你能更专注于代码本身。如果遇到文中未覆盖的特定技术栈环境问题，思路也是一样的：优先寻找官方或社区的包管理支持（Homebrew, ASDF），其次考虑容器化（Docker），最后才是手动安装。保持环境的整洁，就是保持开发心情的舒畅。

编程学习 学习日记 实战经验
← 返回列表