插件 readme.md 渲染失效需检查：必须为 utf-8 无 bom 编码，图片用 ./ 开头的相对路径，禁用 html 标签、mermaid、toc 占位符及 github 风格 emoji；截图用 png 或 mp4 内联，关键信息须全写入 readme.md 首屏。
插件 README.md 渲染失效？检查文件编码与路径格式
VSCode 插件市场（marketplace.visualstudio.com）只渲染插件根目录下的 README.md，且**必须是 UTF-8 无 BOM 编码**。常见失效现象：中文乱码、图片不显示、表格错位、代码块未高亮。根本原因不是语法写错，而是文件保存时被编辑器默认存为 GBK 或 UTF-8 with BOM。
- 用 VSCode 打开
README.md→ 右下角点击编码标识（如“UTF-8”）→ 选择“Save with Encoding” → 选UTF-8 - 图片路径必须为相对路径，且以
./开头（如），绝对路径或 GitHub raw 链接均不生效 - 避免在 README 中使用 VSCode 私有语法，如
%%{init: {'theme': 'base'}}%%（Mermaid 初始化块）、```mermaid块需确保插件市场支持 Mermaid 渲染（目前不支持，会原样显示）
Markdown 语法被截断或样式异常？避开 marketplace 的解析限制
插件市场的 Markdown 渲染器基于旧版 remark，不支持 GFM 扩展语法，也不执行 JS 或 CSS 注入。常见问题包括：TOC 自动生成失败、自定义 HTML 标签被过滤、数学公式不渲染、emoji 显示为原始 :smile: 文本。
- 禁用所有 HTML 标签（
<div>、<code><details></details>、<style></style>），它们会被直接移除 - 不要用
[toc]或[TOC]占位符——市场不识别任何 TOC 插件语法，需手写层级列表 - 代码块必须声明语言（
```json、```ts），否则按纯文本处理，无高亮；但```mermaid和```plantuml不会被渲染成图 - emoji 使用 Unicode 字符（✅、⚠️），而非 GitHub 风格别名（
:white_check_mark:） - 截图建议导出为 PNG，宽度控制在 800px 以内，用
pngquant有损压缩至 150KB 以下 - GIF 推荐转为 MP4（FFmpeg 命令：
ffmpeg -i demo.gif -vcodec libx264 -pix_fmt yuv420p demo.mp4），再用<video></video>标签内联（注意：marketplace 支持<video></video>，但仅限 mp4/webm，且需加controls属性） - 若坚持用 GIF，可转为 base64 内联（
），避免外链失效，但单文件不宜超 500KB - 在
package.json的engines.vscode字段明确限定最低版本（如"^1.77.0"），并在 README 的 Compatibility 表格中同步体现 - Changelog 必须用标准语义化版本（
## v1.2.0 (2026-08-10)），禁用 “New!”、“Fixed!” 等模糊描述；每条变更需标明影响范围（如 “feat: addeditor.action.inlineSuggest.triggersupport”） - Installation 区块第一行就写清命令：
ext install your-publisher.your-extension，不要只写“Search in Extensions view”
截图和 GIF 怎么才不糊、不被压缩？用 base64 内联或托管到可靠 CDN
插件市场会对远程图片做代理加载并强制压缩，导致截图文字模糊、GIF 动画卡顿或丢失。本地 ./images/ 下的图片虽不压缩，但体积过大时加载慢，影响首屏体验。
版本号、兼容性、更新日志怎么写才专业可信？
用户快速决策是否安装，前 3 秒看到的是「Compatibility」「Changelog」和「Installation」区块。混乱的版本标注（如 “v2.x”、“latest”、“beta”）或缺失 VSCode 版本范围，会显著降低信任度。
最易被忽略的一点：插件市场不会拉取 .vscodeignore 之外的任何文件——CHANGELOG.md、LICENSE、docs/ 全部不可见。所有关键信息必须塞进 README.md，且首屏（不滚动）就要交代清楚“它解决什么问题”和“为什么比同类好”。
