linkcode.json

linkcode.json 是位于工作区根目录的可选文件。它声明了 host（即 LinkCode daemon）可以代你运行的脚本 —— 既可以是一次性的 task（任务），也可以是带实时预览的长时运行 service（服务）。每次你打开或运行脚本时，LinkCode 都会重新读取这个文件，因此改动会立即生效，无需重启 host。

Schema

{
  "scripts": {
    "<name>": {
      "type": "task" | "service",
      "command": "string (required)",
      "port": 12345
    }
  }
}

• scripts —— 一个以脚本名为键的对象。这个名字会显示在 Services 列表中，也用于构建脚本的预览主机名。
• type —— "task" 或 "service"。可选；省略时默认为 "task"。
  • task 运行一次即退出。它自身的退出码会被记录；它不获得端口，也没有预览 URL。
  • service 会被保持运行。LinkCode 通过 TCP 对它做健康检查，并为它提供一个代理的预览 URL。关于 service 如何在界面中呈现，参见 Preview。
• command —— 必填，非空。通过你的 shell（/bin/sh -c）运行，工作目录为工作区目录。
• port —— 可选，且仅对 service 有意义。将 service 固定到该 TCP 端口。若省略，LinkCode 会为你挑选一个空闲的 loopback 端口。在 task 上设置 port 无害但会被忽略 —— task 永远不会获得端口。

某个条目格式错误（command 缺失／为空、type 无法识别、port 超出范围）时只会丢弃它自己；文件的其余部分仍会正常加载。

环境变量

LinkCode 运行的每个脚本都会自动向其环境注入以下变量 —— 无需任何配置：

<NAME> 是脚本名转为大写后的形式，其中任何一段非 A–Z 或 0–9 的字符都会被折叠为单个下划线（因此 web-app 变成 WEB_APP）。service 除了 LINKCODE_PORT／LINKCODE_URL 外，还会额外获得属于自己的 LINKCODE_SERVICE_<NAME>_* 一对变量，因此任何脚本 —— 包括 service 自身 —— 都能按名字找到任何已声明的 service。task 则只能看到 LINKCODE_SERVICE_* 变量，因为 task 没有自己的端口。

预览 URL 指向一个 <script>--<workspace>-<hash>.localhost 地址，经由 host 代理，端口与 host 自身正在监听的端口相同（host 的默认端口参见 Local data）。这段短哈希由工作区路径派生而来，因此两个同名工作区不会相互冲突。浏览器和大多数操作系统会自动把 *.localhost 解析到你本机，所以这些 URL 无需任何 DNS 设置即可使用。

有一处命名冲突需要留意：注入到 service 中的 LINKCODE_PORT，与你可以在自己 shell 中设置、用来改变 host 监听端口的 LINKCODE_PORT（local data）无关 —— 在 service 的环境内，注入的值始终优先。

完整示例

{
  "scripts": {
    "web": {
      "type": "service",
      "command": "pnpm dev",
      "port": 3000
    },
    "worker": {
      "type": "service",
      "command": "pnpm dev:worker"
    },
    "test": {
      "command": "pnpm test"
    }
  }
}

• web 是固定在端口 3000 的 service。它的进程会看到 LINKCODE_PORT=3000、LINKCODE_URL=http://web--myproject-a1b2c3.localhost:19523，外加为其同伴准备的 LINKCODE_SERVICE_WORKER_PORT／LINKCODE_SERVICE_WORKER_URL。
• worker 是没有固定端口的 service —— LinkCode 会为它分配一个。它的进程会看到自己的 LINKCODE_PORT／LINKCODE_URL，外加 LINKCODE_SERVICE_WEB_PORT／LINKCODE_SERVICE_WEB_URL。
• test 没有 type，因此默认为 task：触发时运行一次即退出。它不会获得自己的 LINKCODE_PORT，但能看到 LINKCODE_SERVICE_WEB_* 和 LINKCODE_SERVICE_WORKER_* —— 如果你的测试套件需要访问正在运行的开发服务器，这会很有用。