Astro 支持直接使用 .html 文件作为页面路由,需置于 src/pages/ 下,不编译、无 hydration;支持内联 script/style,但不解析 import;插入 HTML 字符串须用 set:html,不可用于用户输入;无样式隔离与脚本优化。

直接用 .html 后缀文件就能写纯 HTML
Astro 默认支持 .html 文件作为页面路由,不需要任何配置。把传统 HTML 页面丢进 src/pages/ 目录下,比如 src/pages/about.html,Astro 就会原样输出它,不编译、不注入 JS、不加 hydration —— 真的就是你写的什么,浏览器就收到什么。
常见错误现象:404 找不到页面,往往是因为文件没放对位置(必须在 src/pages/ 或其子目录),或者用了 .astro 后缀却只写了 HTML 标签(.astro 文件要求至少有一个顶层组件或 )。
- 路径必须是
src/pages/xxx.html,不是public/(那是静态资源,不走路由系统) - HTML 文件里可以写
<script></script>和,Astro 不会动它们 - 不支持
import语句,也不解析 ESM;想用 JS 模块请换.astro或.ts文件
在 .astro 组件里安全嵌入原始 HTML 字符串
如果已有 HTML 片段(比如 CMS 返回的富文本),需要用 set:html 指令插入,而不是直接写 {htmlString} —— 否则 Astro 会转义成纯文本。
使用场景:渲染从 Markdown 解析出的 HTML、第三方 API 返回的 HTML 内容、遗留模板片段。
-
set:html是唯一允许执行“非受控 HTML 插入”的方式,等价于 DOM 的innerHTML - 务必确保内容可信,否则有 XSS 风险;不可直接插用户输入
- 不能和
client:load等指令混用在同一个标签上(Astro 会报错)
示例:
生成可在 deepbi 沙箱 iframe 内运行或作为独立文件运行的交互式 HTML 页面,使用 `window.deepbi` JS SDK 实现数据查询、空间管理、文件浏览及用户操作。当用户提出以下需求时启用该能力: - 创建 KPI 仪表盘、数据表格、文件浏览器、成员列表、管理页面; - 明确要求“转成 dhtml”、“转译成 HTML”、“把 XX 页面转成……”、“控制台页面”、“管理后台”、“DeepBI 页面迁移”; - 提及位于 `apps/console/src/featur
<div set:html="{post.content}/">
<h3>HTML 中需要交互?得手动加 <code>client:load</code> 或换框架组件</h3>
<p>纯 <code>.html</code> 文件里写的 <code><script></script></code> 会被 Astro 保留,但不会做任何优化或隔离 —— 它就是全局脚本,可能和其它页面冲突,也无法按需加载。</p>
<p>性能影响:所有 <code>.html</code> 里的内联脚本都会在首屏加载,无法 code-split,也不能用 Astro 的 island 架构做懒加载。</p>
<ul>
<li>如果逻辑简单且确定只用于当前页,保留在 <code>.html</code> 里没问题</li>
<li>如果要复用、要 SSR 友好、要避免全局污染,应改写为 <code>.astro</code> 组件,并用 <code>client:load</code> 控制 hydrate 时机</li>
<li>
<code>client:load</code> 只对 <code>.astro</code> 或支持的框架组件(React/Vue)生效,对 <code>.html</code> 文件无效</li>
</ul>
<h3>样式隔离?<code>.html</code> 文件不享受 Astro 的 scoped CSS</h3>
<p>Astro 对 <code>.astro</code> 文件中 <code><style></style></code> 块默认加 scope 属性,但 <code>.html</code> 文件里的 <code><style></style></code> 是原样输出的,CSS 会全局生效。</p>
<p>容易踩的坑:多个 <code>.html</code> 页面各自写 <code>.btn { color: red }</code>,最后样式互相覆盖,调试时找不到来源。</p>
<ul>
<li>若需隔离,把样式抽成独立 CSS 文件,用 <code><link rel="stylesheet"></code> 引入(注意路径从 <code>public/</code> 起始)</li>
<li>或者改用 <code>.astro</code> 文件,利用 <code><style></style></code> 的自动 scoped 行为</li>
<li>不要在 <code>.html</code> 里依赖 <code>:global()</code> 之类 Astro 特有语法,它不识别</li>
</ul>
<p>
Astro 做 HTML 集成最麻烦的从来不是“怎么塞进去”,而是“怎么管住它不逃逸”——作用域、脚本生命周期、样式污染,这些都得靠文件类型和写法来硬约束。别指望一个 <code>.html</code> 文件能自动获得现代组件系统的保护。</p>
</div>
前端入门到VUE实战笔记:立即使用
在学习笔记中,你将探索 前端 的入门与实战技巧!










