# HomeBrew

**Repository Path**: markhoo/home-brew

## Basic Information

- **Project Name**: HomeBrew
- **Description**: HomeBrew：Homebrew 国内镜像一键安装与修复脚本（非官方）
- **Primary Language**: Shell
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-22
- **Last Updated**: 2026-08-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Homebrew, brew, homebrew-mirror, homebrew-install, macOS

## README

# HomeBrew

> Homebrew 国内镜像一键安装 / 修复脚本（非官方）

`HomeBrew` 是一个用于在中国大陆网络环境下快速安装和修复 [Homebrew](https://brew.sh/) 的辅助脚本。  
它可以帮助用户安装最新版 Homebrew，并将 Homebrew 的 Bottle、API、brew 仓库切换到国内镜像源，从而显著改善 `brew install`、`brew update` 的下载速度。

> **声明：本项目为第三方辅助工具，不是 Homebrew 官方项目，也不修改 Homebrew 官方源码。**  
> Homebrew 名称与相关标志属于其各自所有者。

---

## 特性

- 支持当前最新版 Homebrew，适配 Homebrew 6.x API 模式
- 支持 macOS Apple Silicon
- 支持 macOS Intel
- 支持 Linux / Linuxbrew
- 默认使用中科大 USTC 镜像源
- 可选清华 TUNA 镜像源
- 自动检测当前 Shell 环境
- 自动写入 `HOMEBREW_API_DOMAIN`、`HOMEBREW_BOTTLE_DOMAIN`、`HOMEBREW_BREW_GIT_REMOTE`
- 自动修复已安装 Homebrew 的镜像源
- 自动备份 Shell 配置文件
- 支持重复运行，不会无限追加配置
- 拦截 root / sudo 执行，避免 Homebrew 权限污染
- 自动识别 Homebrew 安装路径，避免硬编码 `/opt/homebrew` 导致 Intel Mac / Linux 失效

---

## 支持环境

| 系统 | 支持情况 |
| --- | --- |
| macOS Apple Silicon | 支持 |
| macOS Intel | 支持 |
| Linux | 支持 |
| Zsh | 支持 |
| Bash | 支持 |
| Homebrew 6.x | 支持 |

---

## 快速开始

### 方式一：克隆仓库后执行

```bash
git clone https://gitee.com/markhoo/home-brew.git
cd home-brew
chmod +x install-brew.sh
./install-brew.sh
```

### 方式二：下载脚本后执行

```bash
curl -fsSL https://raw.giteeusercontent.com/markhoo/home-brew/raw/main/install-brew.sh -o install-brew.sh
chmod +x install-brew.sh
./install-brew.sh
```

> 不建议直接 `curl ... | bash`。  
> 对于正式开源项目，推荐先下载脚本，审查内容后再执行。

---

## 使用镜像源

### 使用中科大 USTC 镜像源

默认使用 USTC：

```bash
./install-brew.sh
```

或显式指定：

```bash
MIRROR=ustc ./install-brew.sh
```

### 使用清华 TUNA 镜像源

```bash
MIRROR=tuna ./install-brew.sh
```

---

## 脚本会做什么？

运行 `install-brew.sh` 后，脚本会：

1. 检查当前是否为 root / sudo 用户；
2. 检测当前 Shell 类型；
3. 备份已有 Shell 配置文件；
4. 清理旧的 Homebrew 镜像配置；
5. 写入新的 Homebrew 镜像环境变量；
6. 如果检测到 Homebrew 已安装：
   - 修复 `brew` 仓库远程地址；
   - 写入或修复 `brew shellenv`；
   - 执行 `brew update`；
7. 如果未检测到 Homebrew：
   - 下载 Homebrew 安装脚本；
   - 注入国内镜像环境变量；
   - 执行 Homebrew 安装；
   - 自动配置 `brew shellenv`。

---

## 写入的环境变量

脚本默认会写入以下环境变量：

```bash
export HOMEBREW_API_DOMAIN="https://mirrors.ustc.edu.cn/homebrew-bottles/api"
export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.ustc.edu.cn/homebrew-bottles"
export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.ustc.edu.cn/brew.git"
```

如果使用 TUNA，则会写入：

```bash
export HOMEBREW_API_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles/api"
export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles"
export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git"
```

---

## 安装后验证

重启终端，或执行：

```bash
source ~/.zshrc
```

如果您使用的是 Bash，请根据实际情况执行：

```bash
source ~/.bash_profile
```

或：

```bash
source ~/.profile
```

然后验证：

```bash
brew --version
brew config
```

查看 Homebrew 主仓库远程地址：

```bash
cd "$(brew --repo)"
git remote -v
```

测试安装一个软件：

```bash
brew install wget
```

---

## 恢复官方源

如果您希望恢复 Homebrew 官方源，可以删除脚本写入的镜像环境变量，并重置 brew 仓库远程地址。

以 Zsh 为例：

```bash
sed -i.bak -E '/^[[:space:]]*export[[:space:]]+HOMEBREW_/d' ~/.zshrc
rm -f ~/.zshrc.bak
```

然后重新加载配置：

```bash
source ~/.zshrc
```

重置 Homebrew 仓库远程地址：

```bash
git -C "$(brew --repo)" remote set-url origin https://github.com/Homebrew/brew.git
```

更新 Homebrew：

```bash
brew update
```

> 如果您使用的是 Bash，请将 `~/.zshrc` 替换为对应的配置文件，例如 `~/.bash_profile` 或 `~/.profile`。

---

## 常见问题

### 1. 执行后仍然提示 `brew: command not found`

请确认是否已执行：

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

或：

```bash
eval "$(/usr/local/bin/brew shellenv)"
```

或 Linux：

```bash
eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"
```

也可以重启终端后再次执行：

```bash
brew --version
```

---

### 2. 为什么脚本不建议使用 sudo？

Homebrew 不建议以 root 用户运行。  
如果使用 `sudo` 安装或执行 `brew install`，可能会导致 Homebrew 目录权限异常，后续出现大量 `Permission denied` 问题。

---

### 3. 脚本会修改哪些文件？

脚本可能修改以下文件：

```text
~/.zshrc
~/.zprofile
~/.bash_profile
~/.bashrc
~/.profile
```

修改前会自动创建带时间戳的备份文件，例如：

```text
~/.zshrc.bak.1730000000
```

---

### 4. 如何确认镜像是否生效？

执行：

```bash
brew config
```

查看输出中的：

```text
HOMEBREW_API_DOMAIN
HOMEBREW_BOTTLE_DOMAIN
HOMEBREW_BREW_GIT_REMOTE
```

再执行：

```bash
cd "$(brew --repo)"
git remote -v
```

确认 origin 是否指向国内镜像源。

---

### 5. 如果我想自定义 install.sh 下载地址怎么办？

可以编辑 `install-brew.sh` 中的：

```bash
INSTALL_SCRIPT_URL="https://raw.giteeusercontent.com/markhoo/install/raw/main/install.sh"
```

将其替换为您信任的安装脚本地址。

---

## 目录结构

```text
HomeBrew/
├── README.md
├── LICENSE
├── CHANGELOG.md
├── install-brew.sh
├── .gitignore
├── .editorconfig
├── .github/
│   ├── workflows/
│   │   └── ci.yml
│   ├── ISSUE_TEMPLATE/
│   │   ├── bug_report.yml
│   │   └── feature_request.yml
│   └── PULL_REQUEST_TEMPLATE.md
└── docs/
    ├── FAQ.md
    └── MIRRORS.md
```

---

## 开发规范

### ShellCheck

提交代码前请执行：

```bash
shellcheck install-brew.sh
```

### shfmt

建议统一代码格式：

```bash
shfmt -i 2 -ci -w install-brew.sh
```

### 提交规范

建议使用 [Conventional Commits](https://www.conventionalcommits.org/zh-hans/)：

```text
feat: 新增 TUNA 镜像源支持
fix: 修复 Intel Mac shellenv 路径错误
docs: 更新 README 使用说明
ci: 添加 ShellCheck 工作流
chore: 更新版本号
```

---

## 版本管理

本项目遵循 [Semantic Versioning](https://semver.org/lang/zh-CN/)。

版本号格式：

```text
MAJOR.MINOR.PATCH
```

示例：

```text
v1.0.0
```

发布新版本时，请更新：

```text
CHANGELOG.md
```

并创建 Git Tag：

```bash
git tag -a v1.0.0 -m "Release v1.0.0"
git push origin v1.0.0
```

---

## 许可证

本项目采用 [Apache2.0 License](./LICENSE) 开源。

---

## 免责声明

- 本项目为第三方辅助脚本，与 Homebrew 官方无关。
- 本项目不修改、不分发 Homebrew 官方源码。
- 使用本项目前，请自行审查脚本内容。
- 使用国内镜像源即表示您信任对应镜像站。
- 因使用本项目造成的任何损失，由使用者自行承担。

---

## 致谢

- [Homebrew](https://brew.sh/)
- [中科大开源镜像站](https://mirrors.ustc.edu.cn/)
- [清华大学开源软件镜像站](https://mirrors.tuna.tsinghua.edu.cn/)