VSCode装饰器CSS能力受限，仅支持backgroundColor、color、textDecoration等基础属性，不支持background-image、filter、transform等；伪元素before/after仅支持contentText、color等少数样式；border需拆分为borderWidth/borderStyle/borderColor。
vscode.window.createTextEditorDecorationType 的样式边界在哪
装饰器的 CSS 能力受限于 VSCode 编辑器渲染层，不是所有 CSS 都能生效。比如 background-image、filter、transform 会被忽略；font-weight 和 font-style 在行内装饰中基本无效；伪元素 before/after 只支持 contentText、backgroundColor、color、textDecoration 等极少数属性。
常见踩坑点：
-
textDecoration: 'underline wavy red'中wavy不被识别，只保留underline - 写
border: '1px solid #f00'会报错，必须拆成borderWidth、borderStyle、borderColor -
before: { contentText: '⚠' }在高 DPI 屏幕上可能模糊，建议用 SVG data URL 或 Unicode 字符 +fontSize控制大小
setDecorations 调用时机与性能陷阱
每次调用 editor.setDecorations() 都会触发一次 DOM 更新（尽管是虚拟 DOM），高频更新（如输入时逐字符扫描）会导致卡顿。VSCode 官方明确建议：不要在 onDidChangeTextDocument 回调里直接调用，必须加防抖或节流。
实操建议：
- 用
setTimeout延迟 150ms 再执行装饰更新，避免连续输入触发多次重绘 - 缓存上一次匹配的
Range[]，仅当新旧数组不相等时才调用setDecorations - 对大文件（>5000 行）主动跳过装饰，或只处理当前视口范围（
editor.visibleRanges）内的内容 - 避免在
onDidChangeActiveTextEditor中无条件重刷全部装饰——用户切标签页时容易堆积未取消的定时器
正则匹配 vs AST 分析：什么时候该放弃正则
用正则找 TODO 注释或颜色字面量没问题，但一旦涉及嵌套结构、上下文敏感语法（如 JS 模板字符串里的 ${...}、Vue v-if 指令中的表达式），正则就会漏匹配或误匹配。
判断是否该切到 AST：
- 目标文本出现在引号内（如
const color = "#ff6b6b"），且需区分字符串/注释/代码主体 → 必须用语言服务器解析 AST - 需要跨行匹配（如多行注释块、JSX 标签闭合对）→ 正则难维护，AST 更可靠
- 插件要支持 TS/JSX/Vue/Svelte 多语言 → 直接复用
vscode.languages.setTextDocumentLanguage+ 对应语言的 parser（如@typescript-eslint/parser） - 性能可接受前提下，优先走 AST：VSCode 1.80+ 已内置轻量 TS/JS 解析能力，
document.parseTextDocument可直接拿到语法树节点
远程开发（SSH / Dev Container）中装饰器不显示的硬性条件
装饰器是客户端渲染行为，但依赖服务端提供的文档内容和语言模式。远程场景下，editor.setDecorations 调用成功不代表视觉可见——关键要看三个开关是否全开：
-
editor.colorDecorators必须在远程端（即 Dev Container 或 SSH 主机）的settings.json中设为true，本地设置无效 -
color-highlight.enable（若用 Color Highlight）也必须在远程端启用，且color-highlight.languages显式包含当前文件语言（如"javascript"） - 远程端 VSCode Server 版本 ≥ 1.75 —— 旧版存在装饰器跨进程同步 bug，升级后自动修复
- 检查远程端日志：
Developer: Toggle Developer Tools→ Console，过滤decoration，看是否有Failed to apply decorations报错
最常被忽略的是：远程端没装对应语言扩展（如 Volar、ESLint），导致 document.languageId 是 plaintext，装饰器连匹配逻辑都不会触发。
