Skip to Content
文档utoo配置

配置

utoo 从两处读取 TOML 配置：

  • 全局 — ~/.utoo/config.toml，对所有项目生效。
  • 项目 — 项目根目录的 .utoo.toml，为当前项目覆盖全局配置。

文件结构

配置文件可以包含以下 TOML section：

Section用途全局项目
[values]标量配置（镜像源、缓存目录、token、自定义命令等）✓✓（覆盖全局）
[arrays]数组配置（由 utoo 自动维护，如镜像源探测缓存）✓✓
[catalog]monorepo 依赖的默认 catalog—✓
[catalogs.<name>]命名 catalog—✓

一个综合性的项目级 .utoo.toml 示例：

.utoo.toml
[values]
registry = "https://registry.npmjs.org"
 
[catalog]
react = "^18.0.0"
typescript = "^5.0.0"
 
[catalogs.legacy]
debug = "^3.2.7"

[values]

标量键值对。通过 ut config set <key> <value> 写入（加 --global 写入 ~/.utoo/config.toml）。

键默认值描述
registry自动选取npm 镜像源 URL。未设置时 utoo 会在启动时自动挑选最快可达的镜像。
cache-dir~/.cache/nm全局包缓存目录
legacy-peer-depstrue解析依赖时跳过 peer 依赖
manifests-concurrency-limit64最大并发 manifest 请求数
auth-token:<host>—每个 registry 的认证 token，由 ut login 自动写入
<name>.cmd—自定义命令 快捷方式

auth-token:<host> 条目存储在全局配置中，以便跨项目使用。推荐通过 ut login / ut logout 管理，而不是手动编辑。

[arrays]

数组形式的配置项。目前唯一的条目是镜像源 semver 探测缓存，由 utoo 自动维护：

[arrays]
supports-semver = [
  "https://registry.npmmirror.com",
  "!https://registry.npmjs.org",
]
  • 无前缀 — 镜像源支持 semver 查询（/lodash/^4）。
  • ! 前缀 — 不支持。

多个镜像源的探测结果可以同时缓存，切换 --registry 不会触发重新探测。

Catalog

[catalog] 和 [catalogs.<name>] 用于定义 monorepo 内共享的依赖版本。它们仅项目级生效，单独成章：

→ Catalog

优先级

同一个值在多处出现时，按以下优先级从高到低生效：

  1. CLI 参数 — ut install --registry https://...
  2. 环境变量 — UTOO_REGISTRY=https://...
  3. 项目配置 — .utoo.toml 的 [values]
  4. 全局配置 — ~/.utoo/config.toml 的 [values]

[catalog] / [catalogs.*] 不走这条链——它们只从项目配置读取。

环境变量

utoo 行为

变量描述
UTOO_REGISTRY覆盖 npm 镜像源
UTOO_CACHE_DIR覆盖缓存目录
UTOO_SELF_PIN设为 0 时临时跳过 Self Pin
CI设为 1 或 true 时禁用自动更新
UTOO_FORCE_UPDATE设为 1 时强制立即更新
Terminal
UTOO_REGISTRY=https://registry.npmmirror.com ut install

认证

变量描述
NPM_TOKEN当前 registry 的备用认证 token；未存 auth-token:<host> 时使用
NODE_AUTH_TOKEN同 NPM_TOKEN；兼容 GitHub Actions 的 setup-node
GITHUB_TOKEN用于克隆 git+https://github.com/... 依赖；私有仓库或提升速率限制时使用
GH_TOKENGITHUB_TOKEN 的别名；任一个都可用

Registry API 的 token 解析顺序：NPM_TOKEN → NODE_AUTH_TOKEN → 全局配置里的 auth-token:<host>。

网络代理

变量描述
ALL_PROXY所有请求的代理（优先级最高）
HTTPS_PROXYhttps:// 请求的代理
HTTP_PROXYhttp:// 请求的代理

utoo 同时识别大写和小写形式（如 https_proxy）。系统代理的自动检测（macOS / Windows 系统层、Surge / Clash 等工具设置的那种）已禁用——只认显式设置的环境变量。

CLI 配置管理

通过 ut config 命令读写 [values] 条目：

Terminal
# 项目配置（.utoo.toml）
ut config set registry https://registry.npmmirror.com
 
# 全局配置（~/.utoo/config.toml）
ut config set registry https://registry.npmmirror.com --global

自定义命令

任何以 .cmd 结尾的 [values] 键都会注册成一个顶层快捷方式，ut <name> 会执行对应命令串：

Terminal
# 注册快捷方式
ut config set hi.cmd "utx cowsay hi"
ut config set lint.cmd "ut run lint"
 
# 调用
ut hi
ut lint

由于它们属于 [values]，可以用 --global 一次写入全局，所有项目都能用。

镜像源推荐

Terminal
ut config set registry https://registry.npmmirror.com --global

国内用户推荐，速度更快。

Last updated on
utx 别名存储路径