---
metadata:
  - name: generator
    content: Diplodoc Platform v5.52.0
alternate:
  - https://yandex.com/dev/games/doc/en/concepts/local-launch.md
  - https://yandex.com/dev/games/doc/hi/concepts/local-launch.md
  - https://yandex.com/dev/games/doc/ko/concepts/local-launch.md
  - https://yandex.com/dev/games/doc/ru/concepts/local-launch.md
  - https://yandex.com/dev/games/doc/tr/concepts/local-launch.md
  - https://yandex.com/dev/games/doc/vi/concepts/local-launch.md
  - https://yandex.com/dev/games/doc/zh/concepts/local-launch.md
  - href: zh/concepts/local-launch.md
    type: text/markdown
    title: Markdown version
  - href: ../llms.txt
    type: text/markdown
    title: llms.txt
---
> **Documentation Index:** Fetch the complete configuration index at https://yandex.com/dev/games/doc/zh/llms.txt

# 从本地服务器启动

<!-- source: zh/_includes/script-common.md -->
<!-- source: zh/_includes/script/index-js.md -->

<!-- endsource: zh/_includes/script/index-js.md -->

<!-- source: zh/_includes/script/requirements-js.md -->

<!-- endsource: zh/_includes/script/requirements-js.md -->

<!-- source: zh/_includes/script/image-modal-js.md -->

<!-- endsource: zh/_includes/script/image-modal-js.md -->
<!-- endsource: zh/_includes/script-common.md -->

为简化游戏开发和测试流程，您可以从本地服务器运行游戏。测试可在[生产环境](#prod-env)和[开发环境](#dev-env)下进行。

本地服务器运行游戏后，您可以使用SDK的所有功能。



## 生产环境 {#prod-env}

{% note alert %}

需完成[Yandex Games平台注册](../console/manage-account)并创建[游戏草稿](../console/add-new-game#create-draft)。

{% endnote %}

适用于游戏提交审核前的最终测试阶段。此模式下游戏将与真实的Yandex Games平台交互。

特点：

- 游戏通过真实地址在[yandex.com/games](https://yandex.com/games){.external}打开
- 需将外部主机[添加](https://yandex.com/dev/games/doc/zh/console/add-new-game.md#check-host)至CSP规则才能发送请求
- 显示真实广告
- 玩家通过Yandex Passport授权
- 玩家数据和排行榜数据保存在服务器
- 商品目录从服务器加载，购买操作在服务器处理
- 可通过地址栏参数`&debug-mode=16`使用[debug面板](https://yandex.com/dev/games/doc/zh/console/debug-panel.md)

可通过以下方式配置生产环境的本地游戏运行：

- [手动配置](#self-setup)
- [使用npm包配置](#setup-localhost)

### 手动配置本地服务器 {#self-setup}

1. 配置`localhost`服务器
1. 在[草稿模式](../console/test-game)下打开游戏
1. 在地址中添加参数`?game_url=https://localhost`

{% note info %}

出于安全考虑，`game_url`参数仅支持`localhost`域名。

{% endnote %}

### 使用npm包配置本地服务器 {#setup-localhost}

1. 按照[Node.JS](https://nodejs.org/en/){.external}官网说明安装`npm`
1. 通过`npm`安装[@yandex-games/sdk-dev-proxy](https://www.npmjs.com/package/@yandex-games/sdk-dev-proxy){.external}包：

    ```console
    npm install -g @yandex-games/sdk-dev-proxy
    ```

1. 启动游戏。可选择：

   {% list tabs %}

   - 代理到本地服务器

      ```console
      npx @yandex-games/sdk-dev-proxy -h <本地服务器地址>
      ```

   - 指定游戏资源文件夹

       ```console
       npx @yandex-games/sdk-dev-proxy -p <游戏文件夹路径>
       ```

   {% endlist %}

    该包会在游戏所在服务器上代理SDK资源的请求。

若指定`--app-id`参数，启动时将直接在[yandex.com/games](https://yandex.com/games){.external}打开您的游戏：

```console
npx @yandex-games/sdk-dev-proxy -p <游戏文件夹路径> --app-id=<游戏ID>
```

若不指定`--app-id`，控制台将显示服务端游戏模板链接和本地服务器链接。

#### 启动参数 {#start-params}

#|
|| **参数** | **说明** ||
|| `--help` | 显示帮助信息 ||
|| `--host`, `-h` | 游戏本地服务器主机地址（例如用于`webpack-dev-server`） ||
|| `--path`, `-p` | 游戏资源所在文件夹路径 ||
|| `--port` | 服务器开放端口（默认8080） ||
|| `--app-id`, `-i` | 游戏草稿ID ||
|| `--csp`, `-c` | 添加带有`Content-Security-Policy`的meta标签，与服务端`index.html`中创建的标签一致 ||
|| `--log`, `-l` | 在控制台记录请求日志（默认开启） ||
|| `--tld` | 修改`yandex.tld`域名，例如改为`yandex.com`（默认为`ru`） ||
|| `--dev-mode` | 设为`true`时在开发环境下运行游戏（默认为`false`，即生产环境） ||
|#



## 开发环境 {#dev-env}

{% note info %}

无需注册Yandex Games平台或创建游戏草稿。

{% endnote %}

适用于积极开发和调试游戏逻辑阶段。此模式下游戏不与真实Yandex Games平台连接，所有SDK调用均被[mock](*mock)替代，可实现快速页面重载和更新查看。

特点：

- 游戏直接在`https://localhost`打开
- 无CSP限制，可向任何外部主机发送请求
- 使用占位广告替代真实广告，所有回调函数执行方式与生产环境一致
- 通过模拟浏览器对话框实现玩家授权
- 玩家数据和排行榜数据保存在`localStorage`
- 商品目录从[本地文件](#local-catalog-set)加载，玩家购买记录保存在`localStorage`
- 可通过浏览器地址栏设置[参数](#available-params)进行调试
- 浏览器控制台自动按模块分类记录所有SDK调用日志

开发环境同样可通过npm包[@yandex-games/sdk-dev-proxy](https://www.npmjs.com/package/@yandex-games/sdk-dev-proxy){.external}运行。配置说明与[生产环境](#setup-localhost)相同，只需在启动时添加`--dev-mode=true`参数。

可选择：

{% list tabs %}

   - 代理到本地服务器

      ```console
      npx @yandex-games/sdk-dev-proxy -h <本地服务器地址> --dev-mode=true
      ```

   - 指定游戏资源文件夹

       ```console
       npx @yandex-games/sdk-dev-proxy -p <游戏文件夹路径> --dev-mode=true
       ```

{% endlist %}

#### 浏览器地址栏可用参数 {#available-params}

```ts showLineNumbers
export interface SDKMocks {
    /** 是否允许添加快捷方式至桌面？ */
    canShowPrompt?: boolean;
    /** 玩家是否已授权？ */
    isAuthorized?: boolean;
    /** 游戏是否锁定屏幕方向 */
    lockedOrientation?: ELockedOrientation;
}

/** 移动端游戏锁定屏幕方向设置 */
export enum ELockedOrientation {
    /** 仅支持[横屏](*landscape) */
    LANDSCAPE = 'landscape',
    /** 支持双方向 */
    NONE = 'none',
    /** 仅支持[竖屏](*portrait) */
    PORTRAIT = 'portrait',
}
```

**示例**

```text
localhost:8080?mocks={"canShowPrompt":true,"isAuthorized":true,"lockedOrientation":"landscape"}
```

#### 本地商品目录设置 {#local-catalog-set}

为模拟商品目录，请在项目根目录创建`purchases-catalog.json`文件，添加与[开发人员控制台](https://games.yandex.com/console){.external}相同或计划添加的商品列表。开发环境下SDK将从该文件加载商品列表。

**示例**

```json showLineNumbers
[
    {
        "description": "Well styled modern avatar image",
        "id": "avatar",
        "imageURI": "{path-to-image}",
        "price": "100 RUB",
        "priceCurrencyCode": "RUB",
        "priceValue": "100",
        "title": "Premium avatar",
        "getPriceCurrencyImage": "[return ''](*return)"
    }
]
```

调用购买功能时将显示模拟对话框，包含购买成功和取消选项，便于测试两种场景。

[*landscape]: 横屏模式

[*portrait]: 竖屏模式

[*mock]: 用于模拟真实对象的测试替身，在不依赖外部资源或组件的情况下测试代码

[*return]: 可在 `''` 中填入图片路径