用途:为 ElevenLabs 音频项目建立快速、低成本的本地开发工作流。循环围绕三点展开:模拟 SDK 使单元测试不消耗字符配额;用 ELEVENLABS_INTEGRATION=1 显式开关真实 API 调用;开发环境选用更便宜模型、生产保留高质量模型,并配合 tsx watch 热重载和配额检查。
前提:需完成 elevenlabs-install-auth 设置,安装 SDK @elevenlabs/elevenlabs-js,ELEVENLABS_API_KEY 存于 .env.local;Node.js 18+ 与 npm 或 pnpm;推荐安装 vitest 作为测试运行器。
主要步骤:一、建立项目结构 src/elevenlabs/(client、config、tts)、tests/mocks/、tests/fixtures/sample.mp3、被 git 忽略的 output/ 和 .env.local/.env.example。二、编写按 NODE_ENV 选择模型与输出格式的 config.ts,开发用 eleven_flash_v2_5、生产用 eleven_multilingual_v2。三、写 tests/mocks/elevenlabs.ts,从 textToSpeech.convert/stream 返回 sample.mp3,桩化 voices.getAll 和 user.get,使单元测试零成本。四、在 package.json 添加 dev(tsx watch)、test、test:watch、test:integration、generate、quota 脚本。五、添加 src/check-quota.ts 读取 user.subscription,剩余低于 1000 字符时以非零码退出。六、写 tests/tts.test.ts,真实 API 测试用 it.skipIf(!useRealApi),仅在 ELEVENLABS_INTEGRATION=1 时运行,模拟测试始终运行。完整代码见 references/implementation.md,示例见 references/examples.md。
产出:支持 tsx watch 热重载、模拟层、配额检查、集成测试守卫与环境感知模型选择的工作环境。
限制:具体价格、模型费用以外的收费信息暂未提供;错误处理涉及 MODULE_NOT_FOUND、模拟返回 undefined、集成测试失败、开发配额超限等场景。