setup-mac-dev

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

macOS Development Setup

macOS 开发环境搭建

Perform setup directly with tools. Do not offload commands to the user unless a GUI prompt or privileged approval is required.

Use non-interactive flags wherever supported (

-y

--yes

NONINTERACTIVE=1

Before starting, tell the user:

"Setting up this Mac for development now. This may require command-line tools installation and admin approval prompts."

Then execute each step and report concise progress updates.

直接使用工具执行搭建操作。除非需要GUI提示或权限审批，否则不要将命令交给用户执行。

尽可能使用非交互式标志（

-y

、

--yes

、

NONINTERACTIVE=1

）。

开始前，告知用户：

「现在正在为这台Mac配置开发环境。此过程可能需要安装命令行工具，并会弹出权限审批提示。」

然后执行每一步，并提供简洁的进度更新。

Step 1: Preflight checks

步骤1：预检查

Run checks first and record results.

bash

uname -sm
which brew || true
which node || true
which npm || true
which npx || true
which uv || true
xcode-select -p || true

Interpretation:

If required tools already exist, skip reinstallation and keep going.
If
```
xcode-select -p
```
fails, treat missing Command Line Tools (CLT) as a likely blocker for
```
git
```
and Homebrew.

先运行检查并记录结果。

bash

uname -sm
which brew || true
which node || true
which npm || true
which npx || true
which uv || true
xcode-select -p || true

结果说明：

如果所需工具已存在，跳过重新安装，继续下一步。
如果
```
xcode-select -p
```
执行失败，说明缺失Command Line Tools (CLT)，这可能会阻碍
```
git
```
和Homebrew的安装。

Step 2: Ensure Xcode Command Line Tools (mandatory)

步骤2：确保安装Xcode Command Line Tools（必填）

If CLT is missing:

bash

xcode-select --install

Immediately trigger the installer when missing. Do not defer this step.

If the goal is to avoid GUI approval prompts and sudo access is available, prefer a non-GUI install path:

bash

CLT_LABEL="$(softwareupdate -l | awk -F'* ' '/Command Line Tools/ {print $2}' | sed 's/^ *//' | tail -n 1)"
if [ -n "$CLT_LABEL" ]; then
  sudo softwareupdate -i "$CLT_LABEL" --verbose
fi

Notes:

This may open a system dialog and require user acceptance.
```
xcode-select --install
```
does not support a
```
--yes
```
auto-approve flag.
Re-check with
```
xcode-select -p
```
after the install prompt is accepted.
Continue with user-local installs when CLT remains unavailable.

如果缺失CLT：

bash

xcode-select --install

一旦发现缺失，立即触发安装程序，不要推迟此步骤。

如果希望避免GUI审批提示且拥有sudo权限，优先选择非GUI安装路径：

bash

CLT_LABEL="$(softwareupdate -l | awk -F'* ' '/Command Line Tools/ {print $2}' | sed 's/^ *//' | tail -n 1)"
if [ -n "$CLT_LABEL" ]; then
  sudo softwareupdate -i "$CLT_LABEL" --verbose
fi

注意事项：

此操作可能会打开系统对话框，需要用户确认。
```
xcode-select --install
```
不支持
```
--yes
```
自动确认标志。
用户确认安装提示后，重新运行
```
xcode-select -p
```
检查。
如果CLT仍无法安装，继续进行用户本地安装步骤。

Step 3: Install Homebrew when possible

步骤3：尽可能安装Homebrew

Check whether Homebrew already exists:

bash

which brew

If missing, attempt install:

bash

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

If Homebrew install fails due missing admin privileges or CLT, continue with no-admin fallback in Step 4.

检查Homebrew是否已存在：

bash

which brew

如果缺失，尝试安装：

bash

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

如果由于缺少管理员权限或CLT导致Homebrew安装失败，继续执行步骤4中的无权限 fallback 方案。

Step 4: Install Node.js (preferred: Homebrew, fallback: user-local)

步骤4：安装Node.js（优先：Homebrew，备选：用户本地安装）

Preferred path when Homebrew is available:

bash

brew install node

Fallback path without Homebrew:

bash

mkdir -p "$HOME/.local" "$HOME/.local/bin"
curl -fsSL "https://nodejs.org/dist/v22.22.0/node-v22.22.0-darwin-arm64.tar.gz" -o "$HOME/.local/node-v22.22.0-darwin-arm64.tar.gz"
tar -xzf "$HOME/.local/node-v22.22.0-darwin-arm64.tar.gz" -C "$HOME/.local"
ln -sfn "$HOME/.local/node-v22.22.0-darwin-arm64" "$HOME/.local/node"
ln -sfn "$HOME/.local/node/bin/node" "$HOME/.local/bin/node"
ln -sfn "$HOME/.local/node/bin/npm" "$HOME/.local/bin/npm"
ln -sfn "$HOME/.local/node/bin/npx" "$HOME/.local/bin/npx"

Add local bin to current shell session when using fallback:

bash

export PATH="$HOME/.local/bin:$PATH"

当Homebrew可用时，优先选择此路径：

bash

brew install node

无Homebrew时的备选路径：

bash

mkdir -p "$HOME/.local" "$HOME/.local/bin"
curl -fsSL "https://nodejs.org/dist/v22.22.0/node-v22.22.0-darwin-arm64.tar.gz" -o "$HOME/.local/node-v22.22.0-darwin-arm64.tar.gz"
tar -xzf "$HOME/.local/node-v22.22.0-darwin-arm64.tar.gz" -C "$HOME/.local"
ln -sfn "$HOME/.local/node-v22.22.0-darwin-arm64" "$HOME/.local/node"
ln -sfn "$HOME/.local/node/bin/node" "$HOME/.local/bin/node"
ln -sfn "$HOME/.local/node/bin/npm" "$HOME/.local/bin/npm"
ln -sfn "$HOME/.local/node/bin/npx" "$HOME/.local/bin/npx"

使用备选方案时，将本地bin目录添加到当前shell会话的PATH中：

bash

export PATH="$HOME/.local/bin:$PATH"

Step 5: Install uv and Python

步骤5：安装uv和Python

Install uv:

bash

curl -LsSf https://astral.sh/uv/install.sh | sh

Ensure uv is on PATH for the current session:

bash

export PATH="$HOME/.local/bin:$PATH"

Install a managed Python:

bash

uv python install

安装uv：

bash

curl -LsSf https://astral.sh/uv/install.sh | sh

确保uv在当前会话的PATH中：

bash

export PATH="$HOME/.local/bin:$PATH"

安装受管理的Python：

bash

uv python install

Step 6: Install skills packages

步骤6：安装Skills包

Use

npx skills add

with global scope when not inside a project repository:

bash

GH_TOKEN=<token> npx skills add fwfutures/rome2rio-skills fwfutures/vibe-a-thon -g -y

If clone fails (often due CLT/git or auth issues), fallback to zipball workflow:

Download each repository zipball from GitHub API with
```
GH_TOKEN
```
.
Unzip into a temp folder.
Install from local extracted path:

bash

npx skills add /path/to/extracted/repo -g -y

Security note:

Keep tokens in environment variables.
Do not echo tokens into logs or summaries.

当不在项目仓库中时，使用

npx skills add

并加上全局范围参数：

bash

GH_TOKEN=<token> npx skills add fwfutures/rome2rio-skills fwfutures/vibe-a-thon -g -y

如果克隆失败（通常是由于CLT/git或认证问题），使用zipball备选流程：

使用
```
GH_TOKEN
```
通过GitHub API下载每个仓库的zip包。
将zip包解压到临时文件夹。
从本地解压路径安装：

bash

npx skills add /path/to/extracted/repo -g -y

安全注意事项：

将令牌保存在环境变量中。
不要在日志或摘要中输出令牌。

Step 7: Verify tooling and skills

步骤7：验证工具和Skills

Run final verification commands:

bash

export PATH="$HOME/.local/bin:$PATH"
which brew || true
node -v
npm -v
npx -v
uv --version
uv python list
npx skills list -g

运行最终验证命令：

bash

export PATH="$HOME/.local/bin:$PATH"
which brew || true
node -v
npm -v
npx -v
uv --version
uv python list
npx skills list -g

Step 8: Report completion

步骤8：报告完成情况

Provide a concise final report including:

Installed vs already-present tools (
```
brew
```
,
```
node
```
,
```
npm
```
,
```
npx
```
,
```
uv
```
,
```
python
```
)
Skills installed successfully
Any blockers that remain (for example, CLT still pending)
Exact next command if one manual action is still needed

提供简洁的最终报告，包括：

已安装与已存在的工具（
```
brew
```
、
```
node
```
、
```
npm
```
、
```
npx
```
、
```
uv
```
、
```
python
```
）
成功安装的Skills
仍存在的任何阻碍（例如，CLT仍未安装完成）
如果仍需手动操作，提供具体的下一步命令

Troubleshooting quick guide

快速故障排除指南

```
npx: command not found
```
: ensure Node is installed and
```
~/.local/bin
```
is on PATH.
```
Failed to clone repository
```
with xcode-select message: complete CLT install or use zipball fallback.
Homebrew installer asks for sudo/admin: switch to user-local Node path when admin access is unavailable.
```
Agents: not linked
```
in
```
npx skills list -g
```
: installation succeeded; linking depends on host agent runtime.

```
npx: command not found
```
：确保已安装Node，且
```
~/.local/bin
```
已添加到PATH中。
克隆仓库失败并出现xcode-select提示：完成CLT安装或使用zipball备选方案。
Homebrew安装程序要求sudo/管理员权限：当无管理员权限时，切换到用户本地Node安装路径。
```
Agents: not linked
```
在
```
npx skills list -g
```
中显示：安装已成功；链接取决于宿主Agent运行时。