# 资源同步 Q&A：安全使用 `apc resource`

> 本文补充说明 `apc resource` 的行为：会改哪些目录、`-s` 参数的含义，以及同步失败时应该先排查什么。

## 1. `apc resource` 会覆盖我本地写的代码吗？

**问：执行 `apc resource` 会不会把我自己手写的代码覆盖掉？**

**答：不会覆盖你自己维护的业务代码，但会更新「由神岛生成的资源文件」。**

- `apc resource` 主要用于**从神岛地图中拉取共享资源**，例如：
  - UI 配置 / UI 索引文件；
  - 静态资源清单；
  - API 定义、类型定义等。
- 这些同步产物会落在脚手架约定的目录下（例如 `client/`、`server/`、`types/` 下的对应生成文件），并**按约定的路径覆盖同名的已生成文件**。
- **你自己手写的业务逻辑文件（例如 `client/src/...` / `server/src/...`）不会被 `apc resource` 覆盖。**

> 建议：
>
> - 把「生成文件」和「手写业务代码」放在清晰分隔的目录内；
> - 不要手改生成文件的内容，如需修改，请在神岛编辑器中调整配置，然后重新执行 `apc resource`。

## 2. `-s assets` / `-s ui` / `-s api` 分别代表什么？

**问：`apc resource` 的 `-s, --scope` 有哪些可选值？分别会同步什么内容？**

**答：常见的几种 scope 如下（具体以 CLI 文档为准）：**

- `apc resource`（不带 `-s`）

  - 等价于 `-s all`，会同步所有支持的资源类型。

- `apc resource -s assets`

  - 只同步静态资源相关内容（例如：资源清单、路径映射等）。

- `apc resource -s ui`

  - 只同步 UI 相关内容（例如：UI 索引、布局配置等）。

- `apc resource -s api`
  - 只同步与 API / 类型定义相关的内容（例如：接口声明、类型声明等）。

> 实际推荐用法：
>
> - 日常开发中，如果你不确定需要哪一类，直接用 `apc resource` 即可；
> - 如果你非常清楚只改了 UI 或只改了接口，可以用 `-s ui` / `-s api` 精准同步，节省时间。

## 3. 为什么同步会失败？常见原因有哪些？

**问：执行 `apc resource` 时报错，应该先检查什么？**

可以优先检查以下几类问题：

### 3.1 登录信息缺失或已过期

- 是否正确执行过 `apc login`？
- 当前项目的 `.env[.mode]` 或全局配置中，是否存在有效的：
  - `VITE_DAO3_AUTH`
  - `VITE_DAO3_UA`
- 如果是团队新同学，建议先按《登录与授权 Q&A》完成登录后再尝试同步。

### 3.2 地图绑定信息缺失 / 不正确

- `.env[.mode]` 中是否已经配置：
  - `VITE_DAO3_MAP_ID`
  - （必要时）`VITE_DAO3_PLAY_HASH`、`VITE_DAO3_EDIT_HASH`
- 是否已经按推荐流程执行：

  ```bash
  apc list
  apc set <地图ID>
  ```

- 目标地图是否为**扩展地图**，而不是普通地图。

### 3.3 网络 / 权限问题

- 本地网络是否可以正常访问神岛接口域名；
- 当前账号是否对目标地图拥有足够的权限（例如协作权限）。

## 4. 日常开发中，推荐怎么使用 `apc resource`？

**问：我在一个正常的开发周期里，应该什么时候跑 `apc resource`？**

**答：可以参考下面的几个时机：**

- **项目初始化后**：

  - 第一次完成登录 + 地图绑定后，执行一次：

    ```bash
    apc resource
    ```

  - 拉取完整的初始资源到本地。

- **在神岛编辑器中改了 UI / 配置 / 资源之后**：

  - 每次修改完地图侧资源，建议在本地重新执行 `apc resource`，保持本地与线上配置一致。

- **切换地图 / 切换 env 模式之后**：

  - 当你用 `apc set <地图ID> --env dev` 切到另一张地图，或切换到不同的 `.env.<mode>` 时，记得重新同步一次对应环境下的资源。
