配置

本页介绍本地 connect、publish 和 status 工作流。它使用一个配置文件和一个状态根目录，绝不根据当前目录推断它们。可选的自托管 Server 改用项目配置。

配置文件

键	类型	含义
`version`	数字	必须为 `1`。其他值均会被拒绝，也绝不会迁移。
`stateRoot`	字符串，可选	状态根目录。相对值会相对于配置文件所在目录解析。
`providers`	对象，可选	提供商覆盖项。每个键都是提供商 ID，每个值恰好包含一个键 `path`，并相对于配置文件所在目录解析。

{
  "version": 1,
  "stateRoot": "state",
  "providers": {
    "bluesky": { "path": "vendor/bluesky-provider" }
  }
}

未知顶层键会被拒绝。名称看起来像令牌、密钥、密码、API 密钥或凭证的键会按名称拒绝，因此即使意外操作也无法把机密混入配置文件。提供商条目只接受 path，带 URL 方案的路径会被拒绝。

如何选择文件

未提供参数时，CLI 读取 $XDG_CONFIG_HOME/syndroo/config.json；如果 XDG_CONFIG_HOME 未设置或不是绝对路径，则退回 $HOME/.config/syndroo/config.json。
--config 指定明确文件。路径必须为绝对路径；相对路径会被拒绝而不是解析，因此意外执行 --config config.json 不会从工作目录拾取文件。
对于不解析任何提供商的命令，默认文件不存在不构成错误。由 --config 命名的文件不存在则是错误。

文件按严格 JSON 读取：最大 64 KiB，不允许重复键或无效 UTF-8，也不允许 JSON 数据模型无法表示的值。

状态根目录

状态根目录默认为 $XDG_STATE_HOME/syndroo/runtime-v1，找不到时退回 $HOME/.local/state/syndroo/runtime-v1。按照 XDG 基础目录规范的要求，相对 XDG_STATE_HOME 会被忽略。

根目录包含一个格式标记。标记缺失或指向其他格式的根目录会被拒绝：运行时不猜测，也从不探测、迁移或删除早期 Syndroo 版本写入的状态。在从未连接过任何账号的机器上，只读命令会将状态报告为未初始化，而不会创建目录。

环境变量

变量	使用者	含义
`XDG_CONFIG_HOME`	配置	当其为绝对路径时，选择默认配置目录。
`XDG_STATE_HOME`	状态根目录	当其为绝对路径时，选择默认状态目录。
`HOME`	两者	两个默认目录的回退基路径。缺失或为相对值时构成错误。
`SYNDROO_CREDENTIALS`	`--from-env`	一个 JSON 凭证对象，仅在传入 `--from-env` 时读取，最大 64 KiB。
`NO_COLOR`	人类可读输出	禁用颜色，效果类似 `--no-color`。

不会从环境读取其他内容：不读取 .env 文件，没有逐提供商变量注册表，也绝不会从配置文件获取凭证。

Server 配置文件

自托管 Server。Server 命令使用 @syndroo/[email protected] 和 @syndroo/[email protected]。它们使用 syndroo.config.jsonc 保存应用设置，使用 wrangler.jsonc 保存 Worker、D1、队列和 cron 配置。不要提交生成的 wrangler.effective.jsonc、.syndroo/ 或私有服务器状态。

全局 --config 参数用于本地工作流。对于 Server 命令，请从项目运行，或使用 syndroo server --project <directory> <command>。参见部署服务器和Server 命令参考。

安全失败

以下情况全部会被拒绝，而不是猜测：不支持的 version、未知键、看似机密的键、相对的 --config 路径、包含多个键的提供商条目、过大的文件，以及格式标记不匹配的状态根目录。