Astro 集成 Mermaid：客户端渲染选型与模块解析避坑

在 Astro 静态站点中渲染 Mermaid 流程图。 放弃 SSR（服务端预渲染）方案，因为引入 playwright 等无头浏览器内核会导致极重的本地依赖和构建超时。采用纯 CSR（客户端渲染）方案，通过 CDN 引入轻量级 JS，在页面加载时动态接管并替换 DOM。

2. 踩坑点：Astro 编译干预与模块加载报错

现象

控制台抛出致命报错，阻塞页面执行： Uncaught TypeError: Failed to resolve module specifier "[https://cdn...](...)"

根因分析

1. ESM 导入语法污染：从外部复制 CDN 地址时，意外带入了 Markdown 的超链接语法（如 [url](url)），导致原生的 JS import 语句接收到了非法字符串，引擎直接报错。

2. Astro 默认打包拦截：Astro 默认会处理 .astro 文件中的 <script> 标签。如果直接写外部 ESM 引入而不加限制，可能引发构建层面的作用域问题。

解决方案

必须保证 URL 字符串绝对纯净，并强制使用 is:inline 指令跳过 Astro 的本地打包流程。

import mermaid from '[https://cdn.jsdelivr.net/...](https://...)';

<script type="module" is:inline>
  import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs';
</script>