web/index.html是唯一可靠入口，外部css必须通过在中引入，路径须相对于web/目录，如href="css/app.css"；其他方式易致fouc或dom竞争，且css仅对dom元素生效，不作用于canvas渲染的flutter widget。
web/index.html 是唯一可靠入口，外部 CSS 必须通过它加载。其他方式（如 Dart 层注入、@import、JS 动态添加）要么失效，要么引发 FOUC 或 DOM 竞争。
在 web/index.html 的 <link>
Flutter Web 最终运行在浏览器中，web/index.html 是整个页面的根文档。所有样式必须在这里声明，才能进入 document 的样式表队列：
- 打开
web/index.html，在<meta>和<title></title>之后、首个<script></script>之前插入：<link rel="stylesheet" href="css/app.css">
-
href路径必须相对于web/目录 —— 比如文件实际放在web/css/app.css，就写href="css/app.css"；写成href="assets/css/app.css"或href="/assets/css/app.css"都会 404 -
pubspec.yaml不需要声明该 CSS 文件 —— 它不走 Flutter 的 asset bundle，而是由浏览器原生 HTTP 加载 - 避免用
@import在 CSS 内部再引入其他样式，它无加载回调、阻塞渲染、无法监听就绪状态
CSS 只对 DOM 元素生效，不直接作用于 Flutter Widget
Flutter Web 默认使用 CanvasKit 渲染（或 HTML 后端），Container、Text 这类 Widget 不生成标准 DOM 节点，因此原生 CSS 无法选中它们：
- 能生效的场景：你用了
HtmlElementView、IFrameElement、DivElement等封装的原生 DOM 组件，比如自定义视频播放器、嵌入式图表、富文本容器 - 选择器要写对：例如
div.my-video-player可以命中DivElement()..className = "my-video-player"，但不能写.shrink-wrap-render-box（这是 Flutter 内部 class，不稳定且随时可能变） - 全局重置、字体定义、CSS 变量（
:root { --primary: #2196F3; }）可安全使用，后续可通过 JS 桥接读取（如js.JsObject.fromBrowserObject(document.documentElement).callMethod("getComputedStyle", ["--primary"])）
调试常见失败原因
90% 的“CSS 不生效”问题出在路径或作用域上，而不是语法本身：
- 浏览器 DevTools → Network 标签页检查 CSS 请求是否返回 200；404 通常因为：文件没放进
web/、路径大小写错误（macOS/Linux 区分）、IDE 缓存未刷新 - 样式被覆盖？打开 Elements 面板，看目标 DOM 元素的 computed styles，确认你的规则是否被 Flutter 注入的
style标签或 inline style 压制；必要时加!important（仅限调试，生产慎用） - 媒体查询（
@media (prefers-color-scheme: dark)）和伪类（:hover）完全可用 —— 这是原生 CSS 的能力，Flutter 层无法替代 - 不要尝试用
flutter_html或flutter_css_style“模拟”外部 CSS —— 它们只处理内联样式或字符串解析，不支持href、不触发浏览器级加载时序、丢失 @ 规则和字体加载控制
<link>，而是想清楚：这个样式到底要修饰谁？如果是纯 Flutter Widget，就老实用 ThemeData 或 BoxDecoration；只有当你明确需要操作 DOM 节点（比如第三方 JS 库挂载点、自定义 platform view、SEO 友好内容区块），才走 web/index.html 这条路。前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
