@geoql/nuxt-doctor

中文文档
1.10.0发布于 2026/11/04MITTypeScriptES Module构建来源已验证近 30 天下载 6127

CLI auditor for Nuxt 4 apps. Detects anti-patterns, AI-slop, and best-practice violations via @vue/compiler-sfc + oxlint. Run with npx -y @geoql/nuxt-doctor.

原始使用文档
文档目录9 节
  1. Install
  2. Usage
  3. Options
  4. Subcommands
  5. Exit codes
  6. Rules
  7. Scope
  8. Architecture
  9. License

@geoql/nuxt-doctor

Your agent writes bad Nuxt. This catches it.

CLI auditor for Nuxt 4 apps. It runs the same hybrid scan as @geoql/vue-doctor — a template-AST pass over @vue/compiler-sfc plus a script pass through oxlint — and layers Nuxt-specific checks (hydration, server routes, Nitro, SEO, Cloudflare, data-fetching) on top, then merges everything into a deterministic 0–100 score. Built for catching the SSR and auto-import mistakes coding agents leave behind.

Install

# one-off, no install
npx -y @geoql/nuxt-doctor

# or add it
npm i @geoql/nuxt-doctor

Published on npm and JSR with provenance.

Usage

nuxt-doctor [path] [options]

path defaults to the current directory. The default output format is agent (compact, built for LLM consumption), not a verbose human report.

# Audit the project and print the agent report
nuxt-doctor

# Human-readable output, fail the build on warnings
nuxt-doctor --format pretty --fail-on warn

# Machine-readable, only staged files, write to a file
nuxt-doctor --json --staged --output report.json

# Just the score, for piping into a gate
nuxt-doctor --score

Options

FlagDescription
--format <kind>Output format: agent (default), pretty, json, json-compact, sarif, html.
--jsonShorthand for --format json.
--json-compactSingle-line JSON.
--config <path>Path to doctor.config.ts.
--preset <name>Base preset: minimal, recommended, strict, all.
--fail-on <level>Exit non-zero at this severity or worse: error (default), warn, none.
--quietOnly show the summary.
--verboseEmit per-pass timing and rule diagnostics to stderr.
--no-colorDisable colored output.
--rule <id:level>Override one rule, repeatable. Levels: error, warn, info, off. e.g. --rule nuxt-doctor/seo/lang-on-html:off.
--include <glob>Glob of files to include, repeatable.
--exclude <glob>Glob of files to exclude, repeatable.
--no-dead-codeSkip the dead-code (knip) analysis pass.
--no-lintSkip the lint passes (template / SFC / oxlint).
--no-respect-inline-disablesSurface findings even inside doctor-disable comments.
--threshold <n>Minimum passing score, integer 0–100.
--scorePrint only the numeric score, for piping.
--pushAfter the audit, POST privacy-stripped findings to the SaaS. Requires --api-key. Negatable with --no-push.
--no-pushSkip the SaaS push (default).
--push-url <url>SaaS endpoint for --push (default: https://app.the-doctor.report/api/v1/findings).
--api-key <key>API key for the SaaS, sent as the x-api-key header.
--annotationsEmit GitHub Actions ::error:: / ::warning:: lines.
--ciAuto-enable CI behavior (annotations on GitHub Actions).
--no-ciDisable CI auto-detection even when a CI env is set.
--diffOnly report findings in files changed vs HEAD.
--stagedOnly report findings in staged files.
--fullForce a complete scan, overriding --diff / --staged.
--output <file>Write the report to a file instead of stdout.

Severity is error | warn | info everywhere. --diff/--staged, --verbose/--quiet, and --score/--json are mutually exclusive.

Subcommands

CommandDescription
list-rulesList every registered rule with id, severity, category, source, and preset membership. Filters: --preset <recommended|all>, --category <name>, --source <doctor|oxlint-builtin|eslint-plugin-vue>, --severity <error|warn|info>, --json, --json-compact.
explain <ruleId>Print a rule's severity, category, recommendation, and help URL. --json for structured output.
inspect [dir]Print the detected project capabilities doctor uses to gate rules. --json / --json-compact.
nuxt-doctor list-rules --category hydration
nuxt-doctor explain nuxt-doctor/nitro/compatibilityDate-set
nuxt-doctor inspect --json

Exit codes

CodeMeaning
0Clean, or score at/above --threshold and no findings at/above --fail-on.
1Findings at/above the --fail-on level (default: error), or score below --threshold.
2Configuration error or scan failure.

Rules

nuxt-doctor ships ~26 Nuxt rules on top of the full Vue rule set, 59 rules in the registry total. Nuxt categories: structure, nitro, seo, cloudflare, server-routes, hydration, data-fetching, modules-deps, and Nuxt ai-slop; the inherited Vue categories are ai-slop, reactivity, composition, performance, template, template-perf, build-quality, deps, sfc, and dead-code. Run nuxt-doctor list-rules for the live list. Most are on in the recommended preset.

Scope

Nuxt 4 only: the app/ directory layout with compatibilityVersion: 4. For a plain Vue 3 project, use @geoql/vue-doctor.

Architecture

See docs/SPEC.md §10.

License

MIT © Vinayak Kulkarni

版本与发布记录

@geoql/nuxt-doctor 共发布 27 个版本,首次发布于 2026/06/03;过去 12 个月发布了 27 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
1.10.0latest2026/11/0411 天前
1.9.02026/11/0412 天前
1.8.42026/11/0412 天前
1.8.32026/10/2818 天前
1.8.22026/09/122 个月前
1.8.12026/07/283 个月前

其他发布通道:bootstrap → 0.0.0-bootstrap。

关于 @geoql/nuxt-doctor 的常见问题

@geoql/nuxt-doctor 是什么?

CLI auditor for Nuxt 4 apps. Detects anti-patterns, AI-slop, and best-practice violations via @vue/compiler-sfc + oxlint. Run with npx -y @geoql/nuxt-doctor.

如何安装 @geoql/nuxt-doctor?

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

@geoql/nuxt-doctor 支持 TypeScript 吗?

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

@geoql/nuxt-doctor 支持 ESM 还是 CommonJS?

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

@geoql/nuxt-doctor 需要什么版本的 Node.js?

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

@geoql/nuxt-doctor 可以商用吗?

@geoql/nuxt-doctor 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@geoql/nuxt-doctor 的下载量有多少?

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

@geoql/nuxt-doctor 还在维护吗?

最新版本 1.10.0 发布于 2026/11/04(11 天前);至今共发布 27 个版本,其中过去 12 个月发布了 27 个;首次发布于 2026/06/03。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。