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


















