资源同步 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

• 是否已经按推荐流程执行：

  apc list
  apc set <地图ID>

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

3.3 网络 / 权限问题

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

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

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

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

• 项目初始化后：

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

    apc resource

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

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

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

• 切换地图 / 切换 env 模式之后：

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