Skip to content

fix(deploy): 为 Markdown 与纯文本静态资源配置 UTF-8 响应头 - #155

Merged
Dreamwxz merged 1 commit into
Mai-with-u:mainfrom
NovaOPCJ:fix/headers-utf8-charset
Nov 2, 2026
Merged

Dreamwxz merged 1 commit into
Mai-with-u:mainfrom
NovaOPCJ:fix/headers-utf8-charset

Conversation

@NovaOPCJ

@NovaOPCJ NovaOPCJ commented Nov 2, 2026

Copy link
Copy Markdown
Contributor

变更说明

问题背景

浏览器直接访问 https://docs.maibot.chat/installation-agent.md(以及 llms.txt 等纯文本资源)时出现中文乱码(如显示为 å®‰è£…æŒ‡å —)。

原因排查:

  • 静态托管平台(Cloudflare Workers / Pages)默认对 .md 文件返回 Content-Type: text/markdown,对 .txt 文件返回 Content-Type: text/plain,均未携带 ; charset=utf-8。
  • 纯文本/Markdown 文件不具备 HTML 的 <meta charset="utf-8"> 声明,主流浏览器缺乏 charset 参数时会回退至系统或默认字符集(如 windows-1252 或 GBK),导致多字节的 UTF-8 中文字符串解码失败产生乱码。

修复方案

新增 public/_headers 配置文件(VitePress 构建时会自动复制到输出根目录 .vitepress/dist/_headers):

  • 针对 /installation-agent.md、/*.md、/**/*.md 明确声明 Content-Type: text/markdown; charset=utf-8;
  • 针对 /*.txt、/**/*.txt(含 llms.txt、llms-full.txt)明确声明 Content-Type: text/plain; charset=utf-8;
  • 同时附加 Access-Control-Allow-Origin: *,便于 AI 客户端/Web Agent 跨域获取文档上下文。

验证情况

  • 本地执行 pnpm docs:build 验证构建通过,且 .vitepress/dist/_headers 正确生成;
  • 本地执行 node scripts/docs-quality.mjs 门禁 8 项检查全部 0 违规通过。

@Dreamwxz
Dreamwxz merged commit 5448aac into Mai-with-u:main Nov 2, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants