为什么先配置 macOS Homebrew 环境

ElevenLabs 是常见的 AI 语音生成与语音处理工具。很多用户最初会直接打开网页使用，但一旦需要批量生成音频、接入脚本、调用 API、处理本地音频格式，就需要在 Mac 上准备基础开发环境。

macOS 自带部分命令行工具，但版本不一定适合长期使用。因此，更推荐用 Homebrew 管理 Python、Node.js、FFmpeg、Git 等组件。

Homebrew 可以理解为 Mac 上的软件安装管家。你不需要到处下载安装包，也不用手动配置大量路径。大多数工具都可以通过一条命令安装和升级。

对小白来说，先把 Homebrew 配好，再安装 ElevenLabs SDK，会比直接复制网上零散命令更稳定，也更容易排查问题。

适用场景与准备工作

这套配置适合三类用户：

• 第一类：想在 Mac 上用 Python 调用 ElevenLabs 接口生成语音。
• 第二类：希望把 ElevenLabs 接入剪辑、播客、课程音频制作流程。
• 第三类：开发者或内容团队，需要把文本转语音流程做成脚本或内部工具。

开始前，建议确认四件事：

• Mac 系统尽量保持在较新的 macOS 版本。
• 当前用户拥有安装软件的权限。
• 网络能正常访问开发工具下载地址。
• 准备好 ElevenLabs 账户和 API Key。

API Key 相当于调用凭证，只能自己使用。 不要发到群聊、截图或公开仓库中。

第一步：检查 Mac 芯片与终端环境

点击左上角苹果图标，进入“关于本机”，确认芯片类型。如果显示 Apple M 系列，Homebrew 默认路径通常是 /opt/homebrew。如果是 Intel 芯片，常见路径是 /usr/local。这个区别会影响后续环境变量配置。

打开“终端”应用，输入 uname -m 查看架构。返回 arm64 多为 Apple M 系列，返回 x86_64 多为 Intel 架构。再输入 zsh --version，确认当前 shell。近几年 macOS 默认使用 zsh，后续配置一般写入 ~/.zprofile 或 ~/.zshrc。

第二步：安装命令行工具

Homebrew 依赖 Apple 命令行工具。终端输入 xcode-select --install，系统会弹出安装窗口，按提示完成即可。安装过程可能需要几分钟，结束后输入 xcode-select -p。如果能看到类似 /Library/Developer/CommandLineTools 的路径，说明基础工具已就绪。

如果提示已经安装，不需要重复操作。若安装窗口长时间无响应，可以重启终端再试，或在系统设置中查看是否有待完成的软件更新。

不要随意删除系统目录中的 Developer 文件夹。 误删后会导致编译工具和部分安装命令异常。

第三步：安装 Homebrew

在终端输入官方安装命令：/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"。执行后终端会提示将安装哪些内容，按回车继续。过程中可能要求输入 Mac 登录密码，输入时屏幕不显示字符，这是正常现象，输完按回车即可。

安装完成后，Apple M 系列用户通常需要执行提示中的两行环境变量命令。例如，把 Homebrew 加入 ~/.zprofile。常见形式为：echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile，然后执行 eval "$(/opt/homebrew/bin/brew shellenv)"。Intel 用户一般路径为 /usr/local/bin，以终端实际提示为准。

验证安装是否成功，输入 brew --version。能看到版本号即可。再输入 brew doctor，如果显示 Your system is ready to brew，说明环境较干净。如果有 Warning，不一定是严重错误，可以先阅读提示。常见问题多与路径顺序、旧版本工具或权限有关。

第四步：安装 ElevenLabs 常用依赖

建议一次性安装四类工具：

• brew install python：用于运行 Python 脚本。
• brew install node：用于前端或 Node 项目。
• brew install ffmpeg：用于音频转码、切片、格式检查。
• brew install git：用于拉取示例项目和版本管理。

安装后逐项检查：python3 --version、pip3 --version、node -v、npm -v、ffmpeg -version、git --version。这些命令能返回版本信息，说明可被系统识别。若提示 command not found，优先检查 Homebrew 路径是否写入配置文件，并重新打开终端。

第五步：创建独立项目环境

不要把所有 Python 包都装进系统环境，后期容易版本冲突。建议新建一个项目文件夹，例如 mkdir elevenlabs-demo。进入目录后执行 python3 -m venv .venv 创建虚拟环境，再用 source .venv/bin/activate 启用。终端前面出现 (.venv)，表示已经进入独立环境。

随后安装 ElevenLabs Python SDK：pip install elevenlabs python-dotenv。安装完成后可输入 pip show elevenlabs 查看包信息。使用 Node 的用户也可以在项目中执行 npm init -y，再根据官方文档安装对应 SDK。

初学者建议先从 Python 路线开始，代码更直观，调试成本较低。

第六步：配置 API Key 与测试思路

登录 ElevenLabs 后，在账户设置或开发者相关页面找到 API Key。推荐在项目根目录创建 .env 文件，写入 ELEVENLABS_API_KEY=你的密钥，再由脚本读取。

不要把密钥直接写进公开代码，也不要上传到公开托管平台。 可以同时创建 .gitignore，加入 .env 与 .venv/，避免误提交。

测试时，先用一小段普通文本生成短音频，确认请求能成功返回。再逐步增加文本长度、音色参数和输出格式。音频输出建议统一保存到项目的 outputs 文件夹，文件名带日期或用途，方便排查。若需要把 mp3 转为 wav，可使用 FFmpeg，例如 ffmpeg -i input.mp3 output.wav。

小白检查清单

安装前检查：

• macOS 可正常更新。
• 终端可打开。
• 已确认芯片类型。
• 已准备 ElevenLabs 账户。
• 知道 API Key 不能公开。

安装中检查：

• 命令行工具已安装。
• brew --version 有结果。
• brew doctor 无严重报错。
• Python、Node、FFmpeg、Git 都能输出版本号。

项目检查：

• 已创建独立文件夹。
• 已启用 Python 虚拟环境。
• SDK 安装在虚拟环境中。
• 密钥保存在本地环境文件。
• 输出音频文件夹清晰。
• 测试文本足够短，便于快速判断是否成功。

完成这些项目后，再考虑批量生成、自动命名、音频拼接等进阶流程。

常见问题与处理办法

问题一：输入 brew 提示找不到命令。 多数是路径没有生效。Apple M 系列优先检查 /opt/homebrew/bin 是否加入 shell 配置。执行安装结束时提示的 eval 命令，并重新打开终端。

问题二：安装很慢或中断。 可以先确认网络稳定，再重新执行同一条安装命令。Homebrew 通常会继续未完成的任务，不必反复删除目录。若某个包失败，可先执行 brew update，再重新安装指定包。

问题三：Python 包安装成功但脚本仍提示找不到模块。 常见原因是没有启用虚拟环境，或使用了不同的 Python。先执行 which python3 和 which pip，确认路径指向当前项目的 .venv。

问题四：FFmpeg 提示找不到。 先用 ffmpeg -version 检查是否安装。若未安装，执行 brew install ffmpeg。如果已安装但仍不可用，通常还是 PATH 配置问题，按 Homebrew 路径提示修复。

问题五：接口返回认证错误。 优先检查 API Key 是否复制完整，前后是否多了空格，环境变量名是否写错。还要确认当前账户额度、服务状态和调用方式是否符合官方文档。

安全边界与使用建议

使用 AI 语音工具时，要确认文本和声音素材来源合规。不要用来冒充他人、误导听众或制作未经许可的商业内容。企业团队最好建立素材授权记录、生成日志和审核流程，避免后期无法追溯。

API Key 应视为敏感凭证，建议定期更换。 离职交接或电脑送修前及时清理。不要把密钥写入截图、教程素材、公开配置文件或客户端前端代码。若发现密钥可能泄露，应立即在平台后台停用旧密钥并生成新密钥。

从维护角度看，Homebrew 和 SDK 不需要每天升级。稳定项目建议记录当前版本，升级前先备份项目，测试通过后再用于正式流程。若升级后出现异常，可以查看变更说明，必要时回到上一版依赖。

对新手来说，先跑通最小示例，再扩展功能，是最稳妥的安装配置路线。