> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# 安装与配置 - VOICEVOX for Laravel

> 介绍 VOICEVOX for Laravel 的安装方式、根据是否使用 FFI 的不同安装步骤、配置文件、.env 及引擎资源的准备。

## 需要安装什么

VOICEVOX for Laravel 根据你要使用的模式，会有不同的附加包与本地准备。

<Tabs>
  <Tab title="仅客户端">
    如果只需要通过 HTTP 连接官方 VOICEVOX 引擎，只装 `revolution/laravel-voicevox` 即可开始。

    ```shell theme={null}
    composer require revolution/laravel-voicevox
    ```
  </Tab>

  <Tab title="也使用原生 / 引擎 API">
    使用 FFI 的模式还需要同时安装 `revolution/voicevox-core`。

    ```shell theme={null}
    composer require revolution/laravel-voicevox revolution/voicevox-core
    ```
  </Tab>
</Tabs>

## 要求

| 项目            | 内容               |
| ------------- | ---------------- |
| PHP           | 8.3+             |
| Laravel       | 12+              |
| 必需扩展          | `ext-zip`        |
| FFI `ext-ffi` | 原生模式 / 引擎 API 需要 |

<Warning>
  在包括 Laravel Cloud 在内的常见 Web 服务器中 FFI 是禁用的。请在 **本地 CLI** 中尝试原生模式与引擎 API。
</Warning>

## 配置步骤

<Steps>
  <Step title="安装包">
    根据要使用的模式，通过 Composer 安装。原生模式与引擎 API 还需要 [VOICEVOX Core for PHP](/zh/packages/voicevox-core-php)。
  </Step>

  <Step title="发布配置文件">
    ```shell theme={null}
    php artisan vendor:publish --tag="voicevox-config"
    ```
  </Step>

  <Step title="配置 .env">
    仅使用客户端模式请配置 `VOICEVOX_URL`，使用 FFI 时请配置 `VOICEVOX_CORE_PATH`。
  </Step>

  <Step title="按需安装引擎资源">
    使用 `/speaker_info` 或 `/singer_info` 时需要追加资源。
  </Step>
</Steps>

## `config/voicevox.php`

所有配置项均可在 [配置参考](/zh/packages/laravel-voicevox/configuration) 中查阅。

```php theme={null}
return [
    'client' => [
        'url' => env('VOICEVOX_URL', 'http://127.0.0.1:50021'),
        'core_version' => env('VOICEVOX_CLIENT_CORE_VERSION'),
    ],

    'core' => [
        'path' => env('VOICEVOX_CORE_PATH'),
        'dict' => env('VOICEVOX_CORE_DICT_PATH', 'dict/open_jtalk_dic_utf_8-1.11'),
        'models' => env('VOICEVOX_CORE_MODELS_PATH', 'models/vvms'),
        'vvms' => ['0.vvm', '9.vvm', 's0.vvm'],
    ],

    'engine' => [
        'disabled' => env('VOICEVOX_ENGINE_DISABLED', false),
        'fallback_url' => env('VOICEVOX_ENGINE_FALLBACK_URL', 'http://127.0.0.1:50021'),
    ],
];
```

## 最少所需的 `.env`

### 仅客户端模式

如果按默认在 `http://127.0.0.1:50021` 启动官方引擎，则无需额外配置。

```dotenv theme={null}
VOICEVOX_URL=http://127.0.0.1:50021
```

### 原生模式 / 引擎 API

```dotenv theme={null}
VOICEVOX_CORE_PATH=/path/to/voicevox_core/
```

<Info>
  `VOICEVOX_CORE_PATH` 中的内容请按照 [VOICEVOX Core for PHP](/zh/packages/voicevox-core-php) 的步骤准备。库本身、OpenJTalk 词典、模型文件的放置方式也请一并查看该处。
</Info>

## 启用 FFI

在 CLI 中通常可以直接使用。

本地启动 Laravel 版引擎 API 时，请在 `php.ini` 中启用 FFI。

```ini theme={null}
ffi.enable=true
```

FFI 的机制与限制整理在 [PHP FFI](/zh/advanced/ffi) 中。

## 安装引擎资源

使用 `/speaker_info` 或 `/singer_info` 等资源类端点时，需要另行安装资源文件。

```shell theme={null}
php artisan voicevox:install
```

在 Orchestra Testbench 环境中使用以下命令。

```shell theme={null}
vendor/bin/testbench voicevox:install
```

## 各模式的入口

<Columns cols={2}>
  <Card title="客户端 Talk" href="/zh/packages/laravel-voicevox/client-talk" icon="message-circle">
    通过 Docker 启动官方 VOICEVOX 引擎进行文本语音合成。
  </Card>

  <Card title="客户端 Song" href="/zh/packages/laravel-voicevox/client-song" icon="music">
    使用 `Score` 与 `Note` 进行歌声合成。
  </Card>

  <Card title="原生 Talk" href="/zh/packages/laravel-voicevox/native-talk" icon="cpu">
    通过 FFI 直接调用 VOICEVOX CORE。
  </Card>

  <Card title="原生 Song" href="/zh/packages/laravel-voicevox/native-song" icon="music">
    了解歌声模型与 `sync()` 的适用场景。
  </Card>
</Columns>

## 参考链接

* [VOICEVOX for Laravel 概览](/zh/packages/laravel-voicevox)
* [开始使用](/zh/packages/laravel-voicevox/getting-started)
* [配置参考](/zh/packages/laravel-voicevox/configuration)
* [VOICEVOX Core for PHP](/zh/packages/voicevox-core-php)
* [VOICEVOX Core for PHP 用法](/zh/packages/voicevox-core-php/usage)
* [PHP FFI](/zh/advanced/ffi)


## Related topics

- [Laravel Cashier (Stripe)](/zh/cashier.md)
- [引擎 API 模式：Talk（文本语音合成） - VOICEVOX for Laravel](/zh/packages/laravel-voicevox/engine-talk.md)
- [原生模式：Talk（文本语音合成） - VOICEVOX for Laravel](/zh/packages/laravel-voicevox/native-talk.md)
- [开始使用 - VOICEVOX for Laravel](/zh/packages/laravel-voicevox/getting-started.md)
- [原生模式：Song（歌声合成） - VOICEVOX for Laravel](/zh/packages/laravel-voicevox/native-song.md)