vite-plugin-keep-console

vite-plugin-keep-console：Vite 日志管控插件，支持按函数、文件路径、注释标记规则，灵活删除 / 保留 / 上报控制台日志，亦可违规拦截构建。

vite-plugin-keep-console 把生产日志清理从一次性的“删除所有 console.log”升级成构建期策略。Vite 项目可以声明要处理哪些 console 方法、哪些文件参与、哪些注释标记代表可保留诊断、是否只报告不改写，以及 CI 是否应该在发现未批准 console 时失败。

项目定位

这个项目更适合被描述为 Vite 的 console policy 插件。

remove 模式：删除未标记且命中规则的 console 调用。
report 模式：源码保持不变，只记录命中结果，用于审计或渐进迁移。
keep 模式：保留命中的 console，同时仍可汇总报告。
fail gate：开启 failOnConsole 后，把未批准 console 变成构建失败。

核心设计

插件入口保持很小，复杂度放在明确的策略和后端边界里。

:: ConsoleKeeper() 负责归一化配置，在 build 阶段注册 transform hook，buildStart 重置聚合报告，buildEnd 输出报告或根据 failOnConsole 抛错。

:: generateTransform() 负责文件过滤、懒加载 AST 后端、处理 Vue/Svelte <script> 块，并把每个后端的统计合并到构建级报告。

:: Babel 与 OXC 后端共享同一套策略语义。Babel 走 parser/traverse/generator；OXC 走 oxc-parser 与 magic-string。backend: "auto" 会在 Node 版本和依赖允许时优先 OXC，否则自动回退 Babel。

vite-plugin-keep-console 策略流水线

flowchart TD
  Vite["Vite build transform"] --> Match["include / exclude / extension gate"]
  Match --> Blocks["JS/TS/JSX/TSX or Vue/Svelte script blocks"]
  Blocks --> Backend["Babel or OXC AST backend"]
  Backend --> Policy["method filter + keep comments + mode"]
  Policy --> Output["remove / keep / report"]
  Output --> BuildEnd["summary + failOnConsole gate"]

策略面

选项	作用
`backend`	选择 `auto`、`oxc` 或 `babel` 转换后端。
`methods`	限制要处理的 console 方法；为空时处理所有支持的方法。
`include` / `exclude`	基于清理后的文件 id、字符串片段或正则控制作用范围。
`keepComments`	保留带有 `keep-console` 等注释标记的诊断日志。
`mode`	控制未标记命中项是 `remove`、`report` 还是 `keep`。
`report`	在 build end 输出 summary 或 detailed 统计。
`failOnConsole`	发现违反策略的 console 时让构建失败。
`preserveArguments`	删除 console 表达式时保留参数求值，避免隐藏副作用一起丢失。

兼容别名仍然存在：includes 会映射到 methods，external 会映射到 include。

为什么必须用 AST

插件需要知道 console.warn() 是独立语句、三元表达式的一部分、JSX handler 内部调用，还是携带了前导/尾随/参数注释。正则删除无法稳定地区分这些情况。

Babel 后端会把表达式位置的 console 调用替换成 undefined；开启 preserveArguments 后，console.log(expensive(), value) 会被改写成 sequence expression，确保 expensive() 仍然执行。OXC 后端通过 range mutation 和 magic-string 实现同一套行为。

文件类型覆盖

.js、.jsx、.ts、.tsx 按源码模块解析。
.vue 和 .svelte 的 raw 文件只转换 <script> 块。
template 和 markup 保持不变，避免把框架模板语法交给 JS parser。
文件 id 会先去掉 Vite query/hash 后缀，保证 include/exclude 规则稳定。

项目亮点

团队可以显式保留生产诊断，而不是把日志治理完全交给 minifier。
CI 能拦截意外 debug 日志，同时允许带注释标记的运维日志存在。
report-only 模式适合在强制删除前先做迁移审计。
OXC 可以按环境渐进启用，不会让旧 Node/Vite 环境失去 Babel 兜底。

开源信号

TypeScript option 类型清晰，并为旧用户保留兼容别名。
测试覆盖 option 归一化、后端选择、文件类型、策略模式和转换行为。
package exports 对齐 ESM、CJS 和类型声明产物。
英文 README 与中文 README 都说明了策略模型、后端策略和注释放置规则。

适合场景

Vite 应用希望在生产构建阶段治理 console，而不是把策略写进业务代码。
库作者想在发布前得到 console 使用报告。
团队需要区分“生产诊断日志”和“临时 debug 日志”。
项目正在从简单 remove-console 迁移到可审计、可门禁的构建策略。