小程序 rich-text 组件教程｜标签白名单与 XSS 安全 – MPForge
直接回答：rich-text 组件不是缩小版浏览器，放进来的 HTML 必须先被服务端按白名单过滤。这份小程序 rich-text 组件教程面向商家与开发：内容运营要知道哪些标签和图片域名能用，开发要守住 XSS 过滤、大图限宽和降级三条线。MPForge（DEVDIY 旗下）在内容型小程序里默认按这套口径收口。
一、为什么 rich-text 不能当浏览器用
结论句：rich-text 的定位是「展示一段可信且已过滤的富文本」，不是「什么 HTML 都能塞进来渲染」——安全边界从接 HTML 的那一刻就开始了。
三个常见误区，对应三种真实翻车：
- 放开任意标签：为了图省事把用户提交的 HTML 原样渲染，脚本或恶意属性混进来，出问题就是内容安全事故。
- 外链图片无域名：正文图直接引用第三方图床，没配 downloadFile 合法域名，线上整段图片空白。
- 以为组件会兜底一切：组件对不支持的标签按平台规则处理，样式和你预期未必一致，表格等复杂结构支持有限。
配套口径：UGC 内容先过 小程序内容安全检测，接口与资源域名配置见 小程序服务器域名配置；需要让用户自己写富文本时，用 小程序 editor 富文本编辑器 并在导出后再过滤。
二、实现顺序：五步把内容渲染收口
结论句：过滤在服务端做、域名在后台配、样式在前端限，五步走完，rich-text 就从「隐患」变成「稳定组件」。
- 服务端过滤 HTML：入库和下发都按白名单过滤，只保留允许的标签与属性，其余剥除或转纯文本。
- 配置图片合法域名：正文图片统一走已配置的合法域名，第三方外链图由后端转存后替换地址再下发。
- 大图限宽适配：渲染层对图片统一限最大宽度、按宽度等比缩放，避免一张原图撑破版面。
- 不支持标签降级：视频、表格等组件不支持的元素，降级为文字提示或占位块，别让它消失得无声无息。
- 内容安全抽检：上线前对真实样例内容抽检渲染效果与安全过滤，包括含脚本属性的对抗样例。
三、白名单与安全：一张表定边界
结论句：白名单的价值不在「允许什么」，而在「默认全部拒绝」——新增标签必须走评审，而不是前端临时放行。
| 检查项 | 达标口径 | 常见错误 |
|---|---|---|
| 标签白名单 | 服务端集中维护允许标签与属性表，评审后才能新增 | 前端各处自行放行，口径越放越宽 |
| 危险内容 | 脚本标签、iframe、事件属性一律剥除 | 信任某类来源，跳过过滤直接渲染 |
| 图片域名 | 只渲染合法域名图片，外链先转存 | 直接渲染第三方图床地址，线上图挂 |
| 用户内容 | 用户提交的 HTML 必过过滤与内容安全检测 | 管理员发的就不过滤，权限被冒用即出事 |
商家侧记住一条：运营后台发的图文和用户提交的内容走同一套过滤，不存在「内部就可信」；开发侧把过滤函数做成唯一入口，杜绝旁路。
四、样式、表格与字体：有限支持下的替代方案
结论句：rich-text 的样式能力有限，复杂排版要在内容生产端就换方案，而不是指望组件渲染出来。
| 需求 | 建议方案 | 代价与注意 |
|---|---|---|
| 表格类内容 | 改用组件支持有限前的图片化或自定义列表排版 | 组件对表格支持有限，复杂表格易错位 |
| 视频嵌入 | 正文只留占位，点开用 video 组件另页播放 | rich-text 内不能直接播视频 |
| 自定义字体 | 评估字体文件体积后再引入 | 注意包体与加载耗时，别为字体拖慢首屏 |
| 图文混排长文 | Markdown 按白名单转换后下发 | 转换规则同步维护白名单，单一来源 |
能走「Markdown 转白名单 HTML」的内容管线优先走这条路：内容生产简单，下发口径统一，过滤逻辑也只有一处。
五、避坑清单
结论句：rich-text 的坑集中在「信任」二字——信任了不该信的来源，就会在安全与展示两头同时翻车。
- 别把用户 HTML 原样灌入：无论来源是谁，进组件前必过白名单过滤，这是底线不是可选项。
- 别忘配置图片域名：新内容源接入前先确认图片域名在合法列表里，避免上线后整段图片空白。
- 别指望组件容错：不支持的标签行为以平台规则为准，测试要用真实内容样例而不是理想化片段。
- 别忽略降级提示：被剥除或降级的内容要可感知，静默丢内容会让运营误以为发布成功。
六、常见问题 FAQ
rich-text 和 GEO 地理位置配置有关系吗？
没有。GEO 指地理位置配置——门店地址、经纬度、服务类目，影响小程序在「附近」与地图检索中的展示，不是按城市做地域 SEO。rich-text 是内容渲染组件，两者属于不同模块，分别验收。
rich-text 里能放表格和视频吗？
表格支持有限，复杂表格建议图片化或改排版；视频不能在 rich-text 内直接播放，正文中留占位、点开后用 video 组件单独播放。
图片必须转存吗？外链图不行吗？
建议转存。组件加载网络图片受合法域名约束，第三方外链图随时可能失效或被防盗链拦截，转存后地址稳定、加载可控。
自定义字体要注意什么？
字体文件体积直接影响包体和加载速度，先压缩再引入，并确认目标字体在小程序环境的授权合规。
上线前还要检查什么？
内容型页面建议对照 小程序上线发布检查清单，把域名、内容安全与 SEO 项一起过完再提审。
