# mac-environment

**Repository Path**: ConnerClem/mac-environment

## Basic Information

- **Project Name**: mac-environment
- **Description**: Mac电脑，M系列芯片快速搭建基础环境
- **Primary Language**: Shell
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-03
- **Last Updated**: 2026-09-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# mac-environment

在 Mac（Apple Silicon / Intel）上一键搭建日常开发基础环境：

**Homebrew → oh-my-zsh → uv → Vim → Lima（PostgreSQL + Redis）→ Playwright（可选）**

本仓库将 [doc/](doc/) 目录下四篇手动教程自动化为脚本；需要了解原理或排错时，请查阅对应文档。

---

## 特性

- **一条命令安装**：类似 Homebrew 国内安装脚本，curl 即可拉取并执行
- **模块化**：各步骤可单独跳过（`--skip-lima`、`--skip-vim` 等）
- **幂等**：已安装的 Homebrew、oh-my-zsh 等会自动跳过；配置文件会先备份再覆盖
- **Python / uv**：与 `.zshrc` 一致；默认只装 uv，已有 python3 不另装。需要时 `--python=3.12`（预编译，比 pyenv 快）
- **Lima 数据库**：默认 Ubuntu **26.04 LTS Resolute**（apt：**PostgreSQL 18**、**Redis 8**），本机 `127.0.0.1` 访问
- **Playwright 全局化**：浏览器装在家目录 `~/.cache/ms-playwright`，个人配置独立在 `~/.config/mac-environment/clem.zsh`，`.zshrc` 仅 `source` 加载

---

## 前置条件

- macOS（Apple Silicon 或 Intel）
- 可访问 Gitee / GitHub 的网络（首次安装需下载较多内容）
- 磁盘空间建议 ≥ 20 GB（含 Lima 镜像与 pyenv 编译）

---

## 一键安装

> **不要用 `sudo`！** Homebrew 禁止以 root 安装；全程用**普通用户**在终端执行即可。  
> **必须是 Mac 管理员账号**（标准用户不行）。安装 Homebrew 时会提示输入**本机登录密码**，那是正常 sudo，不是让你给整条命令加 `sudo`。

在新 Mac 终端执行（**请整行复制，不要从脚本文件里复制**）：

```bash
curl -fsSL https://gitee.com/ConnerClem/mac-environment/raw/master/install.sh -o /tmp/mac-env-install.sh && bash /tmp/mac-env-install.sh
```

或使用管道（脚本会自动转为临时文件以支持输入密码）：

```bash
/bin/zsh -c "curl -fsSL https://gitee.com/ConnerClem/mac-environment/raw/master/install.sh | bash"
```

默认使用 **Homebrew 官方源**。仅在官方源不可用时再试国内镜像：

```bash
curl -fsSL https://gitee.com/ConnerClem/mac-environment/raw/master/install.sh -o /tmp/mac-env-install.sh && bash /tmp/mac-env-install.sh --cn-mirror
```

**跳过 Lima（只要 Shell / Python / Vim）：**

```bash
curl -fsSL https://gitee.com/ConnerClem/mac-environment/raw/master/install.sh -o /tmp/mac-env-install.sh && bash /tmp/mac-env-install.sh --skip-lima
```

---

## 本地克隆后安装

```bash
git clone https://gitee.com/ConnerClem/mac-environment.git
cd mac-environment
chmod +x install.sh scripts/*.sh config/lima/*.sh
./install.sh
```

---

## 安装步骤


| 步骤  | 脚本                | 说明                                      | 详细文档                                               |
| --- | ----------------- | --------------------------------------- | -------------------------------------------------- |
| 1   | `01-homebrew.sh`  | Homebrew、git、curl、Xcode CLT             | [Mac安装oh-my-zsh.md](doc/Mac安装oh-my-zsh.md)         |
| 2   | `02-oh-my-zsh.sh` | oh-my-zsh、`config/zshrc`、autojump/broot/fortune 等、zsh 插件 | 同上                                                 |
| 3   | `03-uv.sh`        | 安装 uv；有 python3 则跳过；可选 `--python=` | [Mac-Python虚拟环境搭建教程.md](doc/Mac-Python虚拟环境搭建教程.md) |
| 4   | `04-vim.sh`       | Vim、vim-plug、`:PlugInstall`             | [vim配置.md](doc/vim配置.md)                           |
| 5   | `05-lima.sh`      | Lima VM + PostgreSQL + Redis            | [Mac上使用Lima.md](doc/Mac上使用Lima.md)                 |
| 6   | `06-playwright.sh` | 家目录 Playwright + `clem.zsh` 个人配置 | 见下文 Playwright 一节                                 |


---

## 命令行参数

```bash
./install.sh --help                   # 查看全部选项

./install.sh --cn-mirror              # 可选：Homebrew 国内镜像（默认官方）
./install.sh --skip-homebrew          # 跳过 Homebrew（需已安装）
./install.sh --skip-zsh               # 跳过 oh-my-zsh
./install.sh --skip-uv                # 跳过 uv / Python（兼容 --skip-pyenv）
./install.sh --skip-vim               # 跳过 Vim
./install.sh --skip-lima              # 跳过 Lima 数据库虚拟机
./install.sh --skip-playwright        # 跳过 Playwright 全局安装

./install.sh --python=3.12            # 用 uv 安装预编译 Python（失败会降级）
./install.sh --install-python         # 同上，默认 3.12
./install.sh --lima-instance=dev-db   # Lima 实例名（默认 dev-db）
./install.sh --pg-password=secret     # PostgreSQL `postgres` 用户密码
./install.sh --pg-app-db=yundu        # 应用库名（默认 yundu）
./install.sh --pg-app-user=conner     # 应用用户（默认 conner）
./install.sh --pg-app-password=secret # 应用用户密码（默认见文档示例）
./install.sh --redis-password=secret  # Redis `requirepass`（留空则不设密码）
```

---

## 安装完成后

1. **加载 Shell 配置**
  `source ~/.zshrc` 或重新打开终端。
2. **Python（uv）**
  ```bash
  uv --version
  uv venv && source .venv/bin/activate
  uv add requests          # 或 uv sync
  # 需要独立解释器时:
  uv python install 3.12
  ```
3. **数据库（Lima）**
  ```bash
   cat ~/.mac-environment-lima-credentials   # 连接信息
   psql -h 127.0.0.1 -U conner -d yundu      # 默认应用库
   redis-cli -h 127.0.0.1 ping
   limactl shell dev-db                      # 进入虚拟机
   ```
4. **Vim**
  若插件未装全，在 Vim 中执行 `:PlugInstall`。
5. **Playwright（前端 E2E）**
  ```bash
  bash scripts/06-playwright.sh          # 单独执行本步骤
  source ~/.zshrc                        # 加载 ~/.config/mac-environment/clem.zsh
  playwright-browsers                    # 补装 firefox / webkit 等
  ```
  各前端项目仍保留 `@playwright/test` 为 devDependency（类型与配置），但浏览器不再每个项目重复下载。

---

## Playwright 全局安装

重复 `npx playwright install` 主要是因为**浏览器二进制**按项目/按次下载。本仓库改为：

| 路径 | 用途 |
| --- | --- |
| `~/.local/share/pnpm/store` | pnpm 全局 store（同版本包只下载一次） |
| `~/.local/share/playwright` | 全局 `@playwright/test`（pnpm 安装） |
| `~/.cache/ms-playwright` | 共享浏览器（`PLAYWRIGHT_BROWSERS_PATH`） |
| `~/.config/mac-environment/clem.zsh` | **你的**个人 shell 配置（pnpm + Playwright 等） |

主 `~/.zshrc` 里只有一行加载逻辑，具体变量写在 `clem.zsh`，方便你继续加别的个人配置：

```zsh
[[ -r ~/.config/mac-environment/clem.zsh ]] && source ~/.config/mac-environment/clem.zsh
```

`clem.zsh` 会配置 `PNPM_HOME` 与 `PLAYWRIGHT_BROWSERS_PATH`，并设置 `PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1`。前端项目用 `pnpm install` 时，同版本依赖走 pnpm store 硬链接，浏览器也不再每个项目重复下载。

---

## 目录结构

```
mac-environment/
├── install.sh              # curl 一键入口
├── scripts/
│   ├── setup-all.sh        # 总控脚本
│   ├── lib/common.sh       # 公共函数与参数解析
│   ├── 01-homebrew.sh
│   ├── 02-oh-my-zsh.sh
│   ├── 02b-zsh-tools.sh
│   ├── 03-uv.sh
│   ├── 03-pyenv.sh             # 兼容入口 → 03-uv.sh
│   ├── 04-vim.sh
│   ├── 05-lima.sh
│   └── 06-playwright.sh
├── config/
│   ├── zshrc               # oh-my-zsh 配置（与 doc 同步）
│   ├── zshrc.d/clem.zsh    # 个人配置模板 → ~/.config/mac-environment/clem.zsh
│   ├── vimrc               # Vim 配置
│   └── lima/               # Lima YAML 与 VM 内数据库脚本
└── doc/                    # 详细教程与排错说明
```

---

## 环境变量（可选）


| 变量                       | 说明              | 默认值                                          |
| ------------------------ | --------------- | -------------------------------------------- |
| `MAC_ENV_REPO`           | Git 仓库地址        | `https://gitee.com/ConnerClem/mac-environment.git` |
| `MAC_ENV_INSTALL_DIR`    | curl 安装时的克隆目录   | `~/.mac-environment`                         |
| `MAC_ENV_PYTHON_VERSION` | 强制用 uv 安装该 Python | （空，默认不另装） |
| `MAC_ENV_PG_PASSWORD`    | PostgreSQL `postgres` 密码 | `postgres`                                   |
| `MAC_ENV_PG_APP_DB`      | 应用数据库名            | `yundu`                                      |
| `MAC_ENV_PG_APP_USER`    | 应用用户名              | `conner`                                     |
| `MAC_ENV_PG_APP_PASSWORD`| 应用用户密码            | `Conner753951`（开发示例，请按需更换）              |
| `MAC_ENV_REDIS_PASSWORD` | Redis 密码        | （空，不设密码）                                     |


---

## 常见问题

**安装很慢？**  
默认不编译 Python。`--python=` 时 uv 下载**预编译**解释器（通常很快）。Lima 首次下载镜像仍可能较慢。

**脚本可以反复执行吗？**  
可以。Homebrew / oh-my-zsh / uv / Vim 插件 / Lima 实例与数据库配置均做了「已存在则跳过」；配置文件内容未变时不会重复覆盖。

**Lima 启动失败？**  
可查阅 [Mac上使用Lima.md](doc/Mac上使用Lima.md) 中 nerdctl 网络问题；或先 `./install.sh --skip-lima`，之后再单独跑 `scripts/05-lima.sh`。

**只想更新 zshrc / vimrc？**  
修改 `config/` 下文件后，重新执行对应步骤脚本，或手动复制到 `~/`。

**Homebrew 报「stdin is not a TTY / non-interactive mode」？**  
不要用残缺或错误的 curl 命令。请完整复制上面的安装命令；推荐使用 `curl ... -o /tmp/mac-env-install.sh && bash ...` 方式。

**Homebrew 报「Need sudo access / needs to be an Administrator」？**  
1. 确认当前账号是**管理员**（系统设置 → 用户与群组）。  
2. **不要**在整条命令前加 `sudo`。  
3. 安装过程中按提示输入**登录密码**。  
4. 默认已是官方源；仅当官方源不可用时再试 `--cn-mirror`。

**Homebrew 报「不要以 root 身份运行」？**  
说明用了 `sudo`。请**不要**加 sudo，用普通用户重新执行一键命令。

**oh-my-zsh / vim-plug 下载失败？**  
国内网络可能无法访问 GitHub；oh-my-zsh 已内置 Gitee 镜像回退，vim-plug 失败可在网络恢复后重跑 `scripts/04-vim.sh`。

---

## 许可证

见 [LICENSE](LICENSE)