跳到主要内容

Vite 插件

vite-plugin-nudo 将 Nudo 的类型推断集成到 Vite 构建中。文件筛选与 LSP/CLI 同源：经 nudo.analysis.mode（shouldAnalyzeFile）门控；默认 "exports"（含 @nudo:* / export / 侧车的文件）。

安装​

npm install vite-plugin-nudo --save-dev
pnpm add -D vite-plugin-nudo

配置​

在 vite.config.ts 中添加插件：

import { defineConfig } from "vite";
import nudo from "vite-plugin-nudo";

export default defineConfig({
  plugins: [
    nudo(),
    // ... other plugins
  ],
});

选项​

OptionTypeDefaultDescription
includestring[]["**/*.js", "**/*.mjs", "**/*.ts"]要分析的文件 glob 模式（与 isNudoTargetPath 对齐）
excludestring[]["**/node_modules/**", "**/*.d.ts"]要跳过的文件 glob 模式
failOnErrorbooleanfalse设为 true 时，Nudo 类型错误会变为构建错误

带选项的示例​

import { defineConfig } from "vite";
import nudo from "vite-plugin-nudo";

export default defineConfig({
  plugins: [
    nudo({
      include: ["**/*.js", "**/*.mjs"],
      exclude: ["**/node_modules/**", "**/dist/**"],
      failOnError: true,
    }),
  ],
});

glob 模式支持任意扩展名（**/*.js、**/*.mjs、**/*.ts 等）、目录段模式（**/node_modules/**、**/dist/**）；不含通配符的模式按字面量子串与文件路径匹配。

行为​

  • 文件匹配：插件会处理匹配 include 且不匹配 exclude 的文件，exclude 总是优先。默认 include 为 ["**/*.js", "**/*.mjs", "**/*.ts"]，与 isNudoTargetPath 一致（.cjs/.cts/.mts/.tsx 不是分析目标）。
  • 分析门控：glob 之后经 shouldAnalyzeFile（package.json#nudo.analysis.mode）。默认 "exports" — 含 @nudo: / export / 侧车的文件；可配置 "all" / "directives"。
  • 分析：匹配文件使用 @nudojs/service 的 analyzeFileAsync 运行类型推断。
  • 精化门禁：匹配的文件同时会经过 Abs 精化门禁（@nudojs/core 的 checkSource）：nudo:constraint-violated、nudo:assign-mismatch、nudo:arg-structure 问题会并入同一条诊断管线，与求值器诊断一起报告。
  • 缓存：分析结果按文件缓存。缓存在 buildStart 时清除。
  • 诊断：分析产生的错误和警告会作为 Vite 警告发出（当 failOnError 为 true 时为错误）。构建结束时，会输出摘要：[nudo] Analysis complete: X error(s), Y warning(s)。

failOnError​

  • failOnError: false（默认）：Nudo 的类型错误以 Vite 警告形式报告，构建继续。
  • failOnError: true：Nudo 类型错误作为构建错误报告，导致构建失败。

当希望 Nudo 在 CI 或生产构建中强制执行类型正确性时，可使用 failOnError: true。