Front-End-Checklist正确声明 UTF-8 字符编码 —— 从规则定义到 MCP 自动化审查的完整实践【免费下载链接】Front-End-Checklist The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist本篇围绕 Front-End-Checklist 仓库中的charset规则Declare UTF-8 character encoding展开完整继承其规则文档中的声明要求、框架示例与最佳实践并结合仓库内的规则源文件与 MCP 审查工具源码说明这条 critical 级规则如何被自动检测、如何避免误报以及读者最终能掌握声明—验证—自动化审查一套可落地的字符编码治理方案。规则定位与元数据charset规则在仓库中以三层形态存在站点规则源文件、AI Agent 技能文件、MCP 审查工具中的启发式检测。规则源文件为 charset.mdx其 frontmatter 定义了规则的完整元数据title: Declare UTF-8 character encodingdescription: The charset (UTF-8) is declared correctly as the first element in the headcategories:html、seosubcategory:metapriority:critical·difficulty:beginner·estimatedTime: 5 分钟sources: MDN: HTMLprimaryreference、WHATWG HTML Living StandardprimarystandardrelatedRules:viewport、lang-attribute、favicons原因均为同处html/meta区域通常一起审查对应的 Agent 技能文件 SKILL.md 在 frontmatter 中保留了相同的优先级与难度信息priority: critical、difficulty: beginner、estimatedTime: 5并给出aiContextUse when reviewing templates, rendered HTML, or shared components ... Validate the final browser-facing markup, not just the source framework abstraction.这句话是整条规则的审查哲学——字符编码问题最终体现在浏览器收到的 HTML 字节流上而不是框架抽象层因此验证对象永远是最终渲染出的标记。技能文件的 Check / Fix / Explain / Code Review 四段分别定义了对应的操作语义Check验证该 HTML 文档是否在 head 中声明了 UTF-8且位置靠前Fix将meta charsetUTF-8作为 head 中第一个 meta 标签添加Explain解释为什么 UTF-8 对国际化内容支持与字符显示正确性不可或缺Code Review审查输出该标记的模板、服务端渲染 HTML 与共享组件精确标记违反规则的元素、属性与路由。核心要求head 首位声明且落在前 1024 字节内规则文档rule.md 与 charset.mdx 正文一致给出的最小合规示例是一个完整的 HTML 文档!DOCTYPE html html langen head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 titleYour Page Title/title /head body !-- Content with international characters: Café, 北京, العربية -- /body /html其中三个要点直接对应Quick Reference清单meta charsetUTF-8必须是head中的第一个元素必须出现在文档前 1024 字节之内——这是浏览器解析规范对编码声明的硬性窗口浏览器在拿到完整响应头前就开始按块解析 HTML若编码声明超出该窗口浏览器会先用猜测的编码解析早期字节可能导致乱码mojibakeUTF-8 支持所有语言与特殊字符。规则文档同时列出了这条规则被定为critical的四个理由Why It MattersInternational Support让所有 Unicode 字符正确显示示例 body 中的Café、北京、العربية即用于验证多语言渲染Security防止基于字符编码的注入攻击典型的 UTF-7/编码混淆型 XSSEarly Declaration必须位于文档前 1024 字节内Consistency保证跨浏览器、跨平台渲染一致。而 charset.mdx 的whyItMatters字段进一步补充了后果侧描述Missing or incorrect charset causes mojibake (garbled text), broken special characters, and security vulnerabilities from character encoding attacks.框架示例从手写 HTML 到 Vite / Next.js / React规则文档的 Framework Examples 部分覆盖了四种常见技术栈完整内容以 charset.mdx 中的 CodeTabs 组件为规范来源通用 HTML / Vite以index.html为入口的 SPA!-- index.html -- !DOCTYPE html html langen head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 titleVite App/title /head body div idroot/div script typemodule src/src/main.tsx/script /body /htmlNext.js App Router// app/layout.tsx import type { ReactNode } from react export default function RootLayout({ children }: { children: ReactNode }) { return ( html langen body{children}/body /html ) }注意这里没有手写meta charSetUTF-8 /。规则文档对此有明确说明Next.js emits UTF-8 automatically in the document head. Verify the rendered HTML rather than adding a duplicate meta charset tag. 也就是说在框架自动管理 head 的体系中正确姿势是检查最终输出而非重复声明——这一点与下文 MCP 工具的误报抑制逻辑相互印证。Reactreact-helmet 体系import { Helmet } from react-helmet function App() { return ( Helmet meta charSetUTF-8 / /Helmet divYour app content/div / ) }最佳实践三条可执行约束规则文档的 Best Practices 部分给出了一正一反三条约束均可直接复制使用✅Position Early——把 charset 放在所有 meta 标签之前head meta charsetUTF-8 !-- Other meta tags follow -- /head✅Use UTF-8——通用字符支持meta charsetUTF-8❌Avoid Old Syntax——不要使用冗长的 XHTML 等价写法!-- Dont use this -- meta http-equivContent-Type contenttext/html; charsetUTF-8旧语法并非错误但 HTML5 的短形式charsetUTF-8更短、更早落入 1024 字节窗口且可读性更好。源码级实现MCP 工具如何自动检测 charset 违规Front-End-Checklist 的 MCP 包 packages/mcp 提供了review-code工具将规则文档转化为对代码片段的自动审查。charset 规则的启发式检测位于 review-code.ts// Charset check if (slug.includes(charset) || slug.includes(encoding)) { if (hasHeadTag(code) !lowerCode.includes(charset)) { return { hasIssue: true, issue: Missing charset declaration (recommend UTF-8) } } }从源码结构看检测逻辑是两条件合取代码中存在head标签hasHeadTag且全文小写化后找不到charset字样才判定为缺少字符编码声明。这里有一个工程细节值得注意——slug.includes(charset) || slug.includes(encoding)意味着该启发式同时挂载在所有编码相关规则如mime-type、x-content-type等涉及 encoding 的 slug上用同一个轻量信号兜底。更有价值的是配套的误报抑制机制。shouldSuppressIssueForSourceContextreview-code.ts将charset列入了两个白名单if (metadataDrivenSource) { const headManagedRules new Set([ canonical-url, ... charset, content-security-policy, ... viewport, ]) if (headManagedRules.has(ruleSlug)) { return true // 抑制告警 } } if (frameworkDocumentShell) { if (ruleSlug doctype || ruleSlug charset || ruleSlug heading-hierarchy) { return true // 抑制告警 } }从源码结构看这两段分别对应两类表面违规、实际合规的场景metadata 驱动型源码如 Next.js 的metadata导出、框架 head 管理代码head 由框架生成源码片段里当然查不到meta charset框架文档外壳framework document shell如 Next.js 的app/layout.tsx只有html/body骨架charset 由框架自动注入。这正是规则文档中Next.js emits UTF-8 automatically那段说明在工程层面的落地——若工具不做抑制上述两种合规写法都会被Missing charset declaration误伤。配套的单元测试位于 packages/mcp/tests如review-code-detection.test.ts、false-positive-audit.test.ts其中 false-positive-audit 用例专门覆盖这类抑制路径。验证手段与工具规则文档的 Verification 一节给出了自动与手动两条验证路径Automated Checks在浏览器或页面源码中检查最终渲染的 HTML确认规则满足在适用时用 HTML 校验器验证受影响的标记规则源文件的resources字段指向 Nu Html Checker测试一个使用该模式的代表性路由或模板重新检查输出相同标记的共享组件确保修复一致。Manual Checks在代表性路由与支持的目标浏览器上手动验证渲染行为确认用户可见结果符合规则。另外规则文档建议用浏览器 DevTools 的 Network 面板核对响应头——Content-Type: text/html; charsetutf-8是服务端声明编码的另一条途径与meta charset互为佐证。当 meta 标签与 HTTP 头不一致时应以实际生效的编码做对照测试。从仓库自身的实现看Web 应用 next.config.js 中存在/rules/seo/charset到/rules/html/charset的重定向说明该规则已从 seo 类归位到 html 类frontmatter 中仍保留seo作为双分类引用该规则时应使用 html 路径。标准依据与相关规则规则文档的 Standards 一节明确了两项最终裁决标准MDN: HTML——作为最终渲染 HTML 与浏览器行为的参考WHATWG HTML Living Standard——作为最终渲染 HTML 与浏览器行为的标准。charset 并非孤立规则。按 charset.mdx 的relatedRules它与以下同属html/meta区域、通常一起审查的规则组合出现规则源文件均位于 packages/content/rules/en/html/viewportmeta nameviewport与 charset 共同构成 head 最小必需集lang-attributehtml lang与编码声明一起决定用什么语言、用什么编码渲染文档favicons同属 meta 区域的常规审查项doctypedoctype 与 charset 都在 1024 字节窗口内被解析器优先处理两者在 MCP 抑制逻辑中也是同一分支的兄弟规则见上文 review-code.ts。小结charset规则的全部要点可收敛为一句话把meta charsetUTF-8放在head首位、确保它落在文档前 1024 字节内然后用最终渲染的 HTML而非框架源码验证结果。Front-End-Checklist 仓库对这条规则的完整承载方式是charset.mdx 定义规则内容与元数据SKILL.md 与 rule.md 将其包装为 Agent 可执行的 Check/Fix/Explain 技能而 review-code.ts 则提供了带误报抑制的自动检测——三层结构使这条 5 分钟即可完成、却属于 critical 优先级的规则在人工审查与 AI 审查两条链路上都能被一致地执行。【免费下载链接】Front-End-Checklist The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Front-End-Checklist：正确声明 UTF-8 字符编码 —— 从规则定义到 MCP 自动化审查的完整实践
Front-End-Checklist正确声明 UTF-8 字符编码 —— 从规则定义到 MCP 自动化审查的完整实践【免费下载链接】Front-End-Checklist The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist本篇围绕 Front-End-Checklist 仓库中的charset规则Declare UTF-8 character encoding展开完整继承其规则文档中的声明要求、框架示例与最佳实践并结合仓库内的规则源文件与 MCP 审查工具源码说明这条 critical 级规则如何被自动检测、如何避免误报以及读者最终能掌握声明—验证—自动化审查一套可落地的字符编码治理方案。规则定位与元数据charset规则在仓库中以三层形态存在站点规则源文件、AI Agent 技能文件、MCP 审查工具中的启发式检测。规则源文件为 charset.mdx其 frontmatter 定义了规则的完整元数据title: Declare UTF-8 character encodingdescription: The charset (UTF-8) is declared correctly as the first element in the headcategories:html、seosubcategory:metapriority:critical·difficulty:beginner·estimatedTime: 5 分钟sources: MDN: HTMLprimaryreference、WHATWG HTML Living StandardprimarystandardrelatedRules:viewport、lang-attribute、favicons原因均为同处html/meta区域通常一起审查对应的 Agent 技能文件 SKILL.md 在 frontmatter 中保留了相同的优先级与难度信息priority: critical、difficulty: beginner、estimatedTime: 5并给出aiContextUse when reviewing templates, rendered HTML, or shared components ... Validate the final browser-facing markup, not just the source framework abstraction.这句话是整条规则的审查哲学——字符编码问题最终体现在浏览器收到的 HTML 字节流上而不是框架抽象层因此验证对象永远是最终渲染出的标记。技能文件的 Check / Fix / Explain / Code Review 四段分别定义了对应的操作语义Check验证该 HTML 文档是否在 head 中声明了 UTF-8且位置靠前Fix将meta charsetUTF-8作为 head 中第一个 meta 标签添加Explain解释为什么 UTF-8 对国际化内容支持与字符显示正确性不可或缺Code Review审查输出该标记的模板、服务端渲染 HTML 与共享组件精确标记违反规则的元素、属性与路由。核心要求head 首位声明且落在前 1024 字节内规则文档rule.md 与 charset.mdx 正文一致给出的最小合规示例是一个完整的 HTML 文档!DOCTYPE html html langen head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 titleYour Page Title/title /head body !-- Content with international characters: Café, 北京, العربية -- /body /html其中三个要点直接对应Quick Reference清单meta charsetUTF-8必须是head中的第一个元素必须出现在文档前 1024 字节之内——这是浏览器解析规范对编码声明的硬性窗口浏览器在拿到完整响应头前就开始按块解析 HTML若编码声明超出该窗口浏览器会先用猜测的编码解析早期字节可能导致乱码mojibakeUTF-8 支持所有语言与特殊字符。规则文档同时列出了这条规则被定为critical的四个理由Why It MattersInternational Support让所有 Unicode 字符正确显示示例 body 中的Café、北京、العربية即用于验证多语言渲染Security防止基于字符编码的注入攻击典型的 UTF-7/编码混淆型 XSSEarly Declaration必须位于文档前 1024 字节内Consistency保证跨浏览器、跨平台渲染一致。而 charset.mdx 的whyItMatters字段进一步补充了后果侧描述Missing or incorrect charset causes mojibake (garbled text), broken special characters, and security vulnerabilities from character encoding attacks.框架示例从手写 HTML 到 Vite / Next.js / React规则文档的 Framework Examples 部分覆盖了四种常见技术栈完整内容以 charset.mdx 中的 CodeTabs 组件为规范来源通用 HTML / Vite以index.html为入口的 SPA!-- index.html -- !DOCTYPE html html langen head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 titleVite App/title /head body div idroot/div script typemodule src/src/main.tsx/script /body /htmlNext.js App Router// app/layout.tsx import type { ReactNode } from react export default function RootLayout({ children }: { children: ReactNode }) { return ( html langen body{children}/body /html ) }注意这里没有手写meta charSetUTF-8 /。规则文档对此有明确说明Next.js emits UTF-8 automatically in the document head. Verify the rendered HTML rather than adding a duplicate meta charset tag. 也就是说在框架自动管理 head 的体系中正确姿势是检查最终输出而非重复声明——这一点与下文 MCP 工具的误报抑制逻辑相互印证。Reactreact-helmet 体系import { Helmet } from react-helmet function App() { return ( Helmet meta charSetUTF-8 / /Helmet divYour app content/div / ) }最佳实践三条可执行约束规则文档的 Best Practices 部分给出了一正一反三条约束均可直接复制使用✅Position Early——把 charset 放在所有 meta 标签之前head meta charsetUTF-8 !-- Other meta tags follow -- /head✅Use UTF-8——通用字符支持meta charsetUTF-8❌Avoid Old Syntax——不要使用冗长的 XHTML 等价写法!-- Dont use this -- meta http-equivContent-Type contenttext/html; charsetUTF-8旧语法并非错误但 HTML5 的短形式charsetUTF-8更短、更早落入 1024 字节窗口且可读性更好。源码级实现MCP 工具如何自动检测 charset 违规Front-End-Checklist 的 MCP 包 packages/mcp 提供了review-code工具将规则文档转化为对代码片段的自动审查。charset 规则的启发式检测位于 review-code.ts// Charset check if (slug.includes(charset) || slug.includes(encoding)) { if (hasHeadTag(code) !lowerCode.includes(charset)) { return { hasIssue: true, issue: Missing charset declaration (recommend UTF-8) } } }从源码结构看检测逻辑是两条件合取代码中存在head标签hasHeadTag且全文小写化后找不到charset字样才判定为缺少字符编码声明。这里有一个工程细节值得注意——slug.includes(charset) || slug.includes(encoding)意味着该启发式同时挂载在所有编码相关规则如mime-type、x-content-type等涉及 encoding 的 slug上用同一个轻量信号兜底。更有价值的是配套的误报抑制机制。shouldSuppressIssueForSourceContextreview-code.ts将charset列入了两个白名单if (metadataDrivenSource) { const headManagedRules new Set([ canonical-url, ... charset, content-security-policy, ... viewport, ]) if (headManagedRules.has(ruleSlug)) { return true // 抑制告警 } } if (frameworkDocumentShell) { if (ruleSlug doctype || ruleSlug charset || ruleSlug heading-hierarchy) { return true // 抑制告警 } }从源码结构看这两段分别对应两类表面违规、实际合规的场景metadata 驱动型源码如 Next.js 的metadata导出、框架 head 管理代码head 由框架生成源码片段里当然查不到meta charset框架文档外壳framework document shell如 Next.js 的app/layout.tsx只有html/body骨架charset 由框架自动注入。这正是规则文档中Next.js emits UTF-8 automatically那段说明在工程层面的落地——若工具不做抑制上述两种合规写法都会被Missing charset declaration误伤。配套的单元测试位于 packages/mcp/tests如review-code-detection.test.ts、false-positive-audit.test.ts其中 false-positive-audit 用例专门覆盖这类抑制路径。验证手段与工具规则文档的 Verification 一节给出了自动与手动两条验证路径Automated Checks在浏览器或页面源码中检查最终渲染的 HTML确认规则满足在适用时用 HTML 校验器验证受影响的标记规则源文件的resources字段指向 Nu Html Checker测试一个使用该模式的代表性路由或模板重新检查输出相同标记的共享组件确保修复一致。Manual Checks在代表性路由与支持的目标浏览器上手动验证渲染行为确认用户可见结果符合规则。另外规则文档建议用浏览器 DevTools 的 Network 面板核对响应头——Content-Type: text/html; charsetutf-8是服务端声明编码的另一条途径与meta charset互为佐证。当 meta 标签与 HTTP 头不一致时应以实际生效的编码做对照测试。从仓库自身的实现看Web 应用 next.config.js 中存在/rules/seo/charset到/rules/html/charset的重定向说明该规则已从 seo 类归位到 html 类frontmatter 中仍保留seo作为双分类引用该规则时应使用 html 路径。标准依据与相关规则规则文档的 Standards 一节明确了两项最终裁决标准MDN: HTML——作为最终渲染 HTML 与浏览器行为的参考WHATWG HTML Living Standard——作为最终渲染 HTML 与浏览器行为的标准。charset 并非孤立规则。按 charset.mdx 的relatedRules它与以下同属html/meta区域、通常一起审查的规则组合出现规则源文件均位于 packages/content/rules/en/html/viewportmeta nameviewport与 charset 共同构成 head 最小必需集lang-attributehtml lang与编码声明一起决定用什么语言、用什么编码渲染文档favicons同属 meta 区域的常规审查项doctypedoctype 与 charset 都在 1024 字节窗口内被解析器优先处理两者在 MCP 抑制逻辑中也是同一分支的兄弟规则见上文 review-code.ts。小结charset规则的全部要点可收敛为一句话把meta charsetUTF-8放在head首位、确保它落在文档前 1024 字节内然后用最终渲染的 HTML而非框架源码验证结果。Front-End-Checklist 仓库对这条规则的完整承载方式是charset.mdx 定义规则内容与元数据SKILL.md 与 rule.md 将其包装为 Agent 可执行的 Check/Fix/Explain 技能而 review-code.ts 则提供了带误报抑制的自动检测——三层结构使这条 5 分钟即可完成、却属于 critical 优先级的规则在人工审查与 AI 审查两条链路上都能被一致地执行。【免费下载链接】Front-End-Checklist The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考