# @canonical/terrazzo-lsp 中文文档

规范地址：https://npmcn.com/package/%40canonical/terrazzo-lsp/

版本：0\.44\.0
npm 元数据更新时间：2026-10-23T01:40:15.924Z
中文译文更新时间：2026-11-09T05:46:08.829Z
软件包许可：LGPL-3\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40canonical/terrazzo-lsp
原文对照：https://npmcn.com/package/%40canonical/terrazzo-lsp/?lang=original
项目主页：https://github.com/canonical/pragma-core#readme
源码仓库：https://github.com/canonical/pragma-core

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：680 kB，668 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：4 个
- 首次发布：2026-03-08T13:35:46.694Z
- 最新版本发布：2026-10-23T01:40:12.830Z
- 近 30 天下载量：6040（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：26（近 12 个月 26 个）

## 中文简介

语言服务器为设计令牌工作流程提供CSS自定义属性智能. 包括完成、悬浮、诊断、去定义、重命名、文档颜色和工作空间符号.

## 安装

```sh
npm install @canonical/terrazzo-lsp
```

也可以使用：`pnpm add @canonical/terrazzo-lsp`、`yarn add @canonical/terrazzo-lsp`、`bun add @canonical/terrazzo-lsp`

## README

# @canonical/terrazzo-lsp

语言服务器为设计令牌工作流程提供CSS自定义属性智能. 读取 `tokens.json` 构建文物并提供CSS和SCSS文件的编辑功能.

## 特征

| 特性 | 说明 |
| --- | --- |
| 完成情况 | 了解背景的建议 `var(--...)` 参考书目,按类型可转让性、语义层次和出处排列. |
| 缓冲 | 切入元数据,包括已解析的值,颜色监视,别名链条,分级徽章,选择器上下文,以及源位置. |
| 诊断 | 类型不匹配检测,缺失/堆积倒置警告,不可取用符分析,原始用法警告等. |
| 转到定义 | 从一个跳 `var()` 提及象征性声明. |
| 重命名 | 重命名导入图中所有文件中的 CSS 自定义属性 . |
| 文档颜色 | 内置色表和色取器,用于表示后置色值. |
| 语义符号 | 语法突出区分出文物标志,地产,外出参考. |
| 工作空间符号 | 按名称或类型搜索整个工作空间的标志. |

## 编辑器设置

**VS 代码** (建议):

```bash
npm install -D @canonical/design-tokens
npx @canonical/terrazzo-lsp-extension
```

扩展自动检测 `bun` 先掉头 `node >= 22`。 。 。 .

## 国 际

```bash
npx terrazzo-lsp --stdio                # Start LSP server on stdio
npx terrazzo-lsp --stdio --allow-degraded  # Start with reduced capabilities when config is missing
npx terrazzo-lsp check [globs]          # Run diagnostics on CSS files
npx terrazzo-lsp status                 # Show config and artifact status
npx terrazzo-lsp inspect <var>          # Inspect a CSS custom property
npx terrazzo-lsp resolve <spec>         # Resolve an import specifier
npx terrazzo-lsp graph <file>           # Show import graph from a file
```

## 参考文献

LSP发布14个诊断码. CSS诊断在工作空间的每个CSS/SCSS文件中运行. DTCG 诊断在装入时运行一次 `tokens.json` 文物和鉴定是否符合 [DTCG 2025。 10](https://tr.designtokens.org/format/) 规格。 每个诊断可以配置到 `"error"`, (中文(简体) ), `"warning"`, (中文(简体) ), `"info"`,或 `"off"` 内 `terrazzo-lsp.config.json`。 。 。 .

| 代码 | 配置密钥 | 默认 | 说明 |
| --- | --- | --- | --- |
| `css/unknown-var` | `unknownProperties` | 关 | A 类 `var()` 引用不匹配任何已知的自定义属性. |
| `css/missing-fallback` | `missingFallback` | 警告 | A 类 `var()` 提及非艺术财产无倒置价值,无 `@property` 登记。 跳过文物代币,因为这些代币被保证被定义. |
| `css/stale-fallback` | `staleFallback` | 警告 | 倒数一 `var()` 不匹配该符号的当前解析值. |
| `css/type-mismatch` | `typeMismatch` | 错误 | 一个符号的 DTCG 类型与 CSS 属性不相容( 例如: 颜色符号 in `padding`) (中文(简体) ). |
| `css/type-uncertain` | `typeUncertain` | 资讯 | 键入的令牌出现在一个可以接受多个值类型的短手或上下文中. |
| `css/unreachable-token` | `unreachableToken` | 警告 | 该符号的文物输出文件无法通过 `@import` 图表或全局样式表. |
| `css/primitive-token` | `primitiveToken` | 警告 | 直接使用一种原始的代号,在代名词中应优先使用. |
| `css/scoped-usage` | `scopedDeclaration` | 警告 | 在特定选定人范围下宣布的标志在更广泛的范围内使用. |
| `css/no-color-scheme` | `lightDarkNoScheme` | 资讯 | A 类 `light-dark()` 数值没有 `color-scheme` 在选择者或祖先上声明. |
| `dtcg/broken-alias` | `brokenAlias` | 错误 | 文物中的别名指代不存在的代号ID. |
| `dtcg/schema-violation` | `schemaViolation` | 错误 | 表示符的值对其已声明的无效 `$type` (例如:. `$type: color` ),无色值. |
| `dtcg/circular-alias` | `circularAlias` | 错误 | 别名链会形成一个循环——一个符号ID在解析路径中不止一次出现. |
| `dtcg/missing-type` | `inferredType` | 资讯 | 一个标志没有明确的 `$type` 其类型模糊不清. |
| `dtcg/draft-syntax` | `draftFormat` | 资讯 | 符号使用标准化前的字段语法草案(`value`编号 :`type` 无 `$` 前缀). |

### CSS 诊断实例

下面的例子触发一个文件中的每个 CSS 诊断:

```css
/* Assume the following tokens exist in the artifact:
 *   --color-fg           : oklch(17.2% 0 0)        tier: semantic, type: color
 *   --spacing-sm         : 0.5rem                   tier: semantic, type: dimension
 *   --color-palette-blue : oklch(50% 0.15 250)      tier: primitive, type: color
 *   --button-pad         : 0.75rem                  tier: semantic, scoped to .button
 *   --unreachable-token  : 1rem                     (in a file not imported by this sheet)
 */

/* css/unknown-var — off by default, enable via config */
.unknown   { margin: var(--does-not-exist); }

/* css/missing-fallback — no fallback for a non-artifact property */
.missing   { padding: var(--local-pad); }

/* css/stale-fallback — resolved value is 0.5rem, not 16px */
.stale     { gap: var(--spacing-sm, 16px); }

/* css/type-mismatch — colour token in a length context */
.type-err  { width: var(--color-fg); }

/* css/type-uncertain — dimension in a shorthand accepting many types */
.type-warn { background: var(--spacing-sm); }

/* css/unreachable-token — output file not in @import graph */
.unreach   { margin: var(--unreachable-token); }

/* css/primitive-token — prefer semantic alias */
.primitive { color: var(--color-palette-blue); }

/* css/scoped-usage — --button-pad is scoped to .button */
.card      { padding: var(--button-pad); }

/* css/no-color-scheme — light-dark() without color-scheme */
.no-scheme { color: light-dark(black, white); }
```

### DTCG 诊断例

DTCG诊断在符号定义本身的表面问题. 这些出现在 `tokens.json` 文物条目, 不在 CSS 文件中 :

```jsonc
{
  // dtcg/broken-alias — alias target does not exist
  "color.ghost":   { "aliasChain": ["color.nonexistent"], "type": "color" },

  // dtcg/schema-violation — "not-a-colour" is not a valid CSS colour
  "color.invalid": { "valueLight": "not-a-colour", "type": "color" },

  // dtcg/circular-alias — loop-a → loop-b → loop-a
  "color.loop-a":  { "aliasChain": ["color.loop-b", "color.loop-a"], "type": "color" },

  // dtcg/missing-type — no $type field, type is ambiguous
  "spacing.bare":  { "valueLight": "4px", "type": null },

  // dtcg/draft-syntax — uses pre-standard value/type without $ prefix
  "color.legacy":  { "type": "color", "extensions": { "com.terrazzo.draft-syntax": true } }
}
```

### 压制语法

诊断可用下列评论压制:

```css
/* Disable all checks for a region: */
/* terrazzo-lsp-disable */
.suppressed { width: var(--color-fg); }
/* terrazzo-lsp-enable */

/* Disable a specific code for the next line: */
/* terrazzo-lsp-disable css/primitive-token */
.selective { color: var(--color-palette-blue); }
/* terrazzo-lsp-enable css/primitive-token */
```

## 配置

创建一个 `terrazzo-lsp.config.json` 在工作空间根中:

```json
{
  "artifacts": ["@canonical/design-tokens/dist/tokens.json"],
  "globalStylesheets": [".storybook/styles.css"]
}
```

如果没有配置文件, 输出面板记录每个候选路径 尝试,打印一个可复制的启动配置,然后退出。 临时 降低启动、通过 `--allow-degraded`。 。 。 .

```json
{ "artifacts": ["@canonical/design-tokens/dist/tokens.json"] }
```

### 完整配置参考

```json
{
  "artifacts": [],
  "distDir": "dist",
  "scanGlobs": ["src/**/*.css", "src/**/*.scss"],
  "globalStylesheets": null,
  "diagnostics": {
    "unknownProperties": "off",
    "missingFallback": "warning",
    "staleFallback": "warning",
    "typeMismatch": "error",
    "typeUncertain": "info",
    "unreachableToken": "warning",
    "primitiveToken": "warning",
    "scopedDeclaration": "warning",
    "lightDarkNoScheme": "info",
    "brokenAlias": "error",
    "schemaViolation": "error",
    "circularAlias": "error",
    "inferredType": "info",
    "draftFormat": "info",
    "ignoreGlobs": []
  },
  "hover": {
    "showColourSwatches": true,
    "showSelectorContext": true,
    "showProvenanceBadge": true,
    "showAliasChain": true,
    "showSourceLocation": true,
    "showNavigationTier": true,
    "showSpecReferences": true
  },
  "inlayHints": {
    "enabled": false,
    "showColourSwatches": true
  },
  "logLevel": "info"
}
```

| 密钥 | 说明 |
| --- | --- |
| `artifacts` | 路径 `tokens.json` 建造文物. 光谱师解决 `node_modules/`。相对路径必须始于 `./` 或者说 `../`。 。 。 . |
| `distDir` | 目录包含 `*.css.map` 用于源代码映射的文件. |
| `scanGlobs` | CSS/SCSS文件扫描诊断的Glob模式. |
| `globalStylesheets` | CSS文件从每个文档中都隐含可以到达. `null` 指从文物中自动取出. |
| `diagnostics` | 诊断严重性超过。 数值 : `"error"`, (中文(简体) ), `"warning"`, (中文(简体) ), `"info"`, (中文(简体) ), `"off"`。 。 。 . |
| `diagnostics.ignoreGlobs` | 排除诊断文件的 Glob 模式 . |
| `hover` | 切换悬浮弹出物的单个部分. |
| `inlayHints` | 内置提示显示( 默认损坏) . |
| `logLevel` | 服务器日志动词 : `"off"`, (中文(简体) ), `"error"`, (中文(简体) ), `"warn"`, (中文(简体) ), `"info"`, (中文(简体) ), `"debug"`。 。 。 . |

### VS 代码扩展设置

| 设置 | 默认 | 说明 |
| --- | --- | --- |
| `terrazzo-lsp.serverPath` | `""` | 路径 `dist/esm/cli.js`。如果为空,请使用捆绑的服务器. |
| `terrazzo-lsp.runtime` | `""` | 运行时间覆盖 。 空 = 自动检测( E)`bun` 喜欢, `node >= 22` 倒计时). |
| `terrazzo-lsp.trace.server` | `"off"` | `"off"` 只显示启动摘要. `"verbose"` 在输出通道中添加每个请求的痕迹 . |

## 发展

### 建筑

LSP 服务器主要分为四层:

| 层 | 路径 | 责任 |
| --- | --- | --- |
| **议定书** | `protocol/` | JSON- RPC 消息解析, 配置装入, 请求/ 响应匹配 |
| **运行时间** | `runtime/` | 服务器使用寿命周期、文件管理、进口图形建筑、工人调度 |
| **图** | `graph/` | 托肯图数据结构、文物装载、可达性缓存 |
| **供应商** | `providers/` | 所有LSP特征:完成,徘徊,诊断,重命名等. |

**诊断管道:**

```
CSS diagnostics:  orchestrateDiagnostics → per-rule check modules → makeDiagnostic
DTCG diagnostics: produceArtifactDiagnostics → per-rule check modules → makeDiagnostic
```

每个诊断规则都生活在自己的档案中(`diagnostics/checkMissingFallback.ts`, (中文(简体) ), `artifactDiagnostics/checkBrokenAlias.ts`(例如) 与同一地点 `.tests.ts` 文档。 管弦乐团绕过用法(CSS)或道具(DTCG)并代表每个检查功能.

```bash
bun run build      # Compile LSP server (tsc)
bun run test       # Run tests
bun run check      # Lint + type check
```

## 常见问题

### @canonical/terrazzo-lsp 是什么？

语言服务器为设计令牌工作流程提供CSS自定义属性智能\. 包括完成、悬浮、诊断、去定义、重命名、文档颜色和工作空间符号\.

### 如何安装 @canonical/terrazzo-lsp？

在项目目录运行 npm install @canonical/terrazzo-lsp，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 terrazzo-lsp，可以用 npx terrazzo-lsp 直接运行。

### @canonical/terrazzo-lsp 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @canonical/terrazzo-lsp 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @canonical/terrazzo-lsp 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @canonical/terrazzo-lsp 可以商用吗？

@canonical/terrazzo-lsp 使用 LGPL-3\.0 许可。弱 Copyleft：作为库被调用时通常不要求开源你自己的代码，但修改库本身需以 LGPL 开源；前端打包合并后的适用边界存在不同理解。以上为概括，不构成法律意见，请以许可原文为准。

### @canonical/terrazzo-lsp 的下载量有多少？

根据 npm 官方下载统计，@canonical/terrazzo-lsp 在 2026/10/09 – 2026/11/07 这 30 天内被下载 6,040 次，日均约 201 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @canonical/terrazzo-lsp 还在维护吗？

最新版本 0\.44\.0 发布于 2026/10/23（17 天前）；至今共发布 26 个版本，其中过去 12 个月发布了 26 个；首次发布于 2026/03/08。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。