企业官网建设流程全解析

Flutter项目里十有八九的页面都离不开Text。它看起来简单到不需要思考——塞一个字符串，配一个style，就能在屏幕上显示。但一旦项目复杂度上来，你就会被一系列问题缠住：一句话在Row里莫名其妙变成黄色条纹溢出、中英文混排后行高忽高忽低、想给一段文字加点击跳转却只能整段重写、列表里塞了几百条长文本后滑动直接掉帧。这些场景我都在真实App里遇到过，如果你也正在被Text折磨，这篇指南可以帮你把它的底彻底摸清。

这篇内容适合刚看完Flutter教程的新手，也适合已经在用Cubit/Bloc做状态管理、却被文本布局细节卡住的中级开发者。我会从Text的底层渲染链路讲起，把TextStyle、TextSpan、文本量测、文本选择、自定义字体和真实项目里的疑难杂症串起来，全部用可复现的代码和排查思路来讲。读完之后你至少能达成一个目标：拿到任何文本展示相关的需求，不再靠试错，而是直接选对方案。

1. Text组件的渲染链路：从构造参数到屏幕上的一行字

1.1 Text的构造参数：data、style、overflow各自管什么

Text组件表面上是"显示一段文字"，实际它的构造参数却藏着布局、语义、国际化多个维度。最常见的用法是这样：

const Text( 'Hello Flutter', key: Key('hello'), style: TextStyle(fontSize: 16), textAlign: TextAlign.center, maxLines: 1, overflow: TextOverflow.ellipsis, )

这里每个参数的分工其实很明确：data是真正要显示的字符串，style控制视觉表现，maxLines和overflow控制行数及超出后的行为。softWrap则决定是否允许软换行——如果把它设成false，即使空间足够，文字也不会自动折行，而是直接往外溢。这个参数在把Text放进Row、需要强制单行截断的场景里非常关键，很多新人只记得配overflow，却忘了softWrap和maxLines，结果文本依然溢出。

还有一个容易混淆的点：Text和Text.rich不是两个组件，Text.rich只是让data变成TextSpan的另一种构造方式。底层逻辑仍然是同一个Text组件把字符串转换成TextSpan再交给渲染层。所以你在调试工具里翻widget树时，会看到Text的build方法直接返回了一个RichText，而不是什么专门的"TextRenderWidget"。这一点理解之后，很多"为什么Text不能单独加点击事件"之类的困惑就自然解开了：因为Text只是语法糖，真正干活的是它内部的TextSpan。

1.2 样式从哪来：DefaultTextStyle的继承与覆盖规则

Text不写style也能显示，是因为Flutter在MaterialApp层面就为你铺了一层默认文本样式。这个默认样式的载体叫DefaultTextStyle，它是一个InheritedWidget，作用范围覆盖整个子树。也就是说，你在MaterialApp下面任意位置写一个Text，它都会自动拿到这层样式。

但很多人不知道的是，Text自己的style并不会整体替换DefaultTextStyle，而是按字段合并。举个例子：

DefaultTextStyle( style: const TextStyle(fontSize: 14, color: Colors.grey), child: Column( children: [ const Text('继承了全局灰色和14号字'), const Text( '只覆盖颜色', style: TextStyle(color: Colors.blue), ), const Text( '完全脱离继承', style: TextStyle( fontSize: 12, color: Colors.black, inherit: false, ), ), ], ), )

第一行Text什么都没传，最终显示的样式完全来自DefaultTextStyle。第二行只给了color，那fontSize依然继承全局的14，颜色变成蓝色。第三行显式写了inherit: false，此时Text不会再去和父级样式合并，所以你给什么就显示什么，没给的字段全部回到系统默认值——这个行为经常让人意外：有人设了inherit: false却只给了color，结果字号变成默认大小。

从底层看，这个合并逻辑实际上是把DefaultTextStyle.style和Text.style通过TextStyle.merge串在一起。理解这条继承链，对排查"为什么Text颜色不跟随主题""为什么字号莫名变小"这类问题特别有用。

1.3 最终画字的是谁：RichText与RenderParagraph的底层关系

Text的build方法里有这样一层逻辑：如果构造时传了textSpan，就直接使用它；否则用data包一层TextSpan。然后这个TextSpan被交给RichText，而RichText对应的RenderObject是RenderParagraph。

RenderParagraph是一个RenderBox，它做两件事：layout阶段调用TextPainter计算文本的宽高和换行结果，paint阶段调用Canvas把文字画出来。所以你在项目里写的每一个Text，最终都会落到一个RenderParagraph上面。这个链路解释了为什么Text会在某些情况成为性能瓶颈：RenderParagraph.didUpdateWidget之后会重新执行文本布局，而文本布局本身是一个相当重的过程，包括字体shape、换行计算、基线对齐等。如果父组件频繁setState，页面里几十个Text就会跟着全部重新布局。这点我们放到后面性能部分细说，这里只需要记住：Text并非轻量组件，它背后有一套独立的布局系统。

2. TextStyle细节全解：字体、行高和中英文混排不出问题的关键

2.1 TextStyle字段速查表：哪些常用、哪些真有坑

TextStyle字段非常多，但真正日常用到且容易踩坑的，我用一张表整理如下：

表里最关键的两组互斥关系是color与foreground、background与backgroundColor。因为foreground本质上是一个Paint对象，它接管了文字的最终绘制，所以你在foreground里画了颜色，color字段就不会再生效。我见过不少同学改了半天的color不生效，最后才发现是上层封装组件里偷偷设置了foreground。

2.2 height字段不是行高，而是行高倍数

TextStyle里的height非常容易让人误解。它不是绝对的行高像素值，而是“行高倍数”。一般情况下，渲染引擎会以fontSize * height作为行高基准，再把文本基线对齐到这个行高区域内。所以：

Text( '行高示例', style: TextStyle(fontSize: 14, height: 1.2), )

这段代码的实际渲染行高大约是14 * 1.2 = 16.8，但引擎并不是简单地把每个字形拉伸到这个高度，而是把每一行的上下间隙均匀分配到文字区域的上下两侧，让线条看起来整体更规整。用生活化的话说，height就像给每一行文字套了一个透明盒子，盒子的高度是fontSize的倍数，文字在这个盒子里上下居中。

这个字段最大的价值是解决中英文混排时的行高不一致。不同字体对ascent和descent的定义不同，英文字体可能顶部空隙小，中文字体顶部空隙大。当一行里同时出现中文和英文时，如果不统一设置height，行高会被“撑”得很不稳定，视觉上换行后忽高忽低。只要给TextStyle统一设置一个height值，中英文的行高就会被强行拉齐。真实项目里我基本都会给正文文本设置height: 1.2到1.4，不是为了好看，而是为了跨平台显示一致。

2.3 fontFamily与fontFamilyFallback：中文场景必须搞清楚

在Flutter里指定字体有两种常见做法：一种是整个App主题里设置fontFamily，另一种是给单个Text设置。但如果你只设置一个不包含中文字形的字体，比如：

Text( '你好 hello', style: TextStyle( fontFamily: 'Roboto', ), )

在Android上中文通常还能通过系统字体回退显示，但如果你打包的是一个自定义英文字体，或者在某些Web/桌面环境里，中文就可能变成一个个“豆腐块”。这时候fontFamilyFallback就派上用场了：

Text( '你好 hello', style: TextStyle( fontFamily: 'Roboto', fontFamilyFallback: ['PingFang SC', 'Noto Sans CJK SC', 'Microsoft YaHei'], ), )

fontFamilyFallback是一个列表，Flutter会按顺序尝试，直到找到一个包含当前字形“glyph”的字体。注意它只对fontFamily里没找到的字形生效，不是“替换整个字体”。

实际项目里我建议：如果你的设计稿明确要求英文用某个品牌字体、中文用苹方或思源黑体，就用fontFamily+fontFamilyFallback的组合。如果设计稿没有特殊字体要求，干脆不要设置fontFamily，让系统字体处理一切，反而最省事。

2.4 响应系统字体缩放：textScaleFactor已过时，用textScaler

Flutter默认会读取系统的字体缩放设置，用户在系统设置里把字体调大，App里的Text会跟着放大。这个行为由MediaQuery里的textScaler控制，早期版本的textScaleFactor字段已经在较新版本里被废弃。

如果你不希望文字被系统缩放影响，有两种做法。一种是对单个Text关闭缩放：

Text( '固定字号', textScaler: TextScaler.noScaling, )

另一种是对全局统一限制缩放范围，防止界面被极端缩放撑爆：

MediaQuery.withClampedTextScaling( minScaleFactor: 0.8, maxScaleFactor: 1.3, child: MaterialApp(...), )

这里强调的是，设计稿往往基于固定像素，但用户的可访问性需求也很重要。TextScaler.noScaling虽然能让布局稳定，却会牺牲无障碍体验。我一般建议项目里用withClampedTextScaling限定上下限，而不是完全禁止缩放。

3. 富文本实战：用TextSpan和WidgetSpan实现可点击、可混合的文本

3.1 TextSpan事件响应：recognizer的挂载与销毁

普通Text无法只让“其中一段文字”响应点击，因为整段文本是一个整体。要打破这个限制，需要用Text.rich配合TextSpan的recognizer参数。最常见的场景是用户协议和隐私政策里的“同意”文案：

class AgreementText extends StatefulWidget { const AgreementText({super.key}); @override State<AgreementText> createState() => _AgreementTextState(); } class _AgreementTextState extends State<AgreementText> { late final TapGestureRecognizer _userAgreementRecognizer; late final TapGestureRecognizer _privacyPolicyRecognizer; @override void initState() { super.initState(); _userAgreementRecognizer = TapGestureRecognizer() ..onTap = () { // 跳转到用户协议页 }; _privacyPolicyRecognizer = TapGestureRecognizer() ..onTap = () { // 跳转到隐私政策页 }; } @override void dispose() { _userAgreementRecognizer.dispose(); _privacyPolicyRecognizer.dispose(); super.dispose(); } @override Widget build(BuildContext context) { return Text.rich( TextSpan( text: '我已阅读并同意', children: [ TextSpan( text: '《用户协议》', style: const TextStyle(color: Colors.blue), recognizer: _userAgreementRecognizer, ), const TextSpan(text: '和'), TextSpan( text: '《隐私政策》', style: const TextStyle(color: Colors.blue), recognizer: _privacyPolicyRecognizer, ), ], ), textAlign: TextAlign.center, ); } }

这里最容易翻车的点有两个。

第一个是recognizer必须被显式dispose。如果你在State里每次都new一个TapGestureRecognizer却不释放，Flutter会在接收到手势时抛出类似“A TapGestureRecognizer was used after being disposed”的报错，或者造成内存泄漏。正确做法是把recognizer定义为State的成员变量，在dispose()里清理。

第二个是如果你写了const Text.rich(...)，里面就不能含有运行期创建的recognizer，因为const要求在编译期就完全确定。需要点击事件时，这段代码不能加const。

3.2 WidgetSpan内嵌组件的布局对齐与回收坑

TextSpan除了能放文字，还能通过WidgetSpan把一个真正的Widget嵌进文本流。这在实现"文字 + 内联图标"时非常方便：

Text.rich( TextSpan( children: [ const WidgetSpan( alignment: PlaceholderAlignment.middle, child: Icon(Icons.home, size: 16), ), const TextSpan(text: ' 回到首页'), ], ), )

WidgetSpan看起来只是把Widget塞进去，实际有两个坑：

一是alignment的默认值是PlaceholderAlignment.baseline，意思是组件底部对齐到文本的基线上。对于很多图标场景，这个默认值会让图标看起来偏上或偏下，你需要根据设计稿选择top、middle或bottom。如果选择baseline，还可以通过baseline参数指定基线偏移量。

二是WidgetSpan里的Widget不继承文本的TextStyle，所以它也不会跟随父级Text的textScaler缩放。你放大系统字体时，文字变大了，图标可能还是16像素，视觉上就错位了。解决办法是在WidgetSpan内部自己读取MediaQuery.textScalerOf(context)，手动对图标尺寸做缩放。

另外，如果WidgetSpan里的Widget在列表项里被频繁重建，它也会跟着走完整的widget mount/unmount周期。如果只是展示静态图标，尽量把child写成const，减少重建成本。

3.3 实战案例：实现一个简单的@提及高亮

聊天场景里的@高亮，非常适合用TextSpan拆分实现。核心思路是用正则把文本切成普通片段和高亮片段，然后分别构造TextSpan：

List<TextSpan> _parseMentions(String message, void Function(String mention) onTap) { final regex = RegExp(r'@([\u4e00-\u9fa5\w]+)'); final spans = <TextSpan>[]; int start = 0; for (final match in regex.allMatches(message)) { if (match.start > start) { spans.add(TextSpan(text: message.substring(start, match.start))); } final mention = match.group(0)!; spans.add( TextSpan( text: mention, style: const TextStyle(color: Color(0xFF4E7FFF)), recognizer: TapGestureRecognizer() ..onTap = () => onTap(mention), ), ); start = match.end; } if (start < message.length) { spans.add(TextSpan(text: message.substring(start))); } return spans; }

用的时候：

Text.rich( TextSpan(children: _parseMentions('今天 @小明 和 @小红 都来了', _openProfile)), )

有一件事必须提醒：上面代码里每次调用_parseMentions都会new出新的TapGestureRecognizer，如果消息列表很长，列表滚动后这些recognizer不会自动释放，潜在内存风险很大。生产环境建议把recognizer集合统一管理，比如在State里维护一个List<TapGestureRecognizer>，在dispose时统一清理。这个细节，常规教程很少写，但对聊天类长列表很重要。

4. 文本量测与溢出控制：从TextPainter到"展开/收起"组件

4.1 什么时候需要手动量测文本：TextPainter的正确用法

Flutter没有提供同步获取Text宽高的“傻瓜api”，因为Text的布局依赖父级约束。但在某些场景，你必须在布局前知道文本到底有多宽多高，比如画布绘制、气泡自适应高度、给文本动态拼接后缀。这时就要用到TextPainter：

double measureTextWidth(String text, TextStyle style, {double maxWidth = double.infinity}) { final painter = TextPainter( text: TextSpan(text: text, style: style), maxLines: 1, textDirection: TextDirection.ltr, )..layout(maxWidth: maxWidth); final width = painter.width; painter.dispose(); return width; }

注意几点：layout(maxWidth: ...)之后才能读取width和height；maxLines会影响高度计算；用完的TextPainter必须dispose，否则会有内存压力。TextPainter内部会持有字体和段落缓存，频繁创建销毁时尽量不要在build方法里直接同步执行，可以放到compute或缓存结果。

如果你把maxWidth传成double.infinity，TextPainter就会按单行文本测量宽度。如果传入有限宽度和maxLines，它就会模拟多行换行，并且可以通过didExceedMaxLines判断是否溢出。

4.2 三种溢出模式的选择：ellipsis、clip和fade

Text的overflow有四种枚举，但实际常用的是ellipsis、clip、fade三种：

ellipsis虽然最常用，但它只能做尾部省略。如果你需要“中间省略”效果，比如保留文件名前缀和后缀、中间用省略号代替，Flutter原生并没有现成开关，必须自己测量组合。思路是先量测完整文本宽度，再测量前缀和后缀各需要多少空间，最后在中间填充省略号。这也是一个典型的TextPainter手测场景。

另外，ellipsis必须配合有限的maxLines或宽度约束才会生效。如果既不设maxLines，父级宽度又是无限的，字符串会一直延伸，省略号永远不会出现。

4.3 从零实现展开/收起：测量-截断-渲染三步走

“展开/收起”是长文本展示里最高频的自定义需求。原生Text只有截断能力，没有“点击查看全文”的能力，所以需要自己封装。核心流程是三步：测量完整文本是否溢出，二分找到最后一个不溢出的位置，截断并追加“展开”按钮。

下面是一个简化但可用的实现，为了可读性省略了部分边界处理：

class ExpandableText extends StatefulWidget { const ExpandableText({ super.key, required this.text, this.style, this.maxLines = 3, }); final String text; final TextStyle? style; final int maxLines; @override State<ExpandableText> createState() => _ExpandableTextState(); } class _ExpandableTextState extends State<ExpandableText> { bool _expanded = false; String? _truncated; String? _computeTruncatedText(double maxWidth) { if (_expanded || maxWidth == 0) return null; final fullPainter = TextPainter( text: TextSpan(text: widget.text, style: widget.style), maxLines: widget.maxLines, textDirection: TextDirection.ltr, )..layout(maxWidth: maxWidth); final shouldTruncate = fullPainter.didExceedMaxLines; fullPainter.dispose(); if (!shouldTruncate) return null; int low = 0; int high = widget.text.length; while (low < high) { final mid = (low + high) >> 1; final painter = TextPainter( text: TextSpan( text: widget.text.substring(0, mid) + '…', style: widget.style, ), maxLines: widget.maxLines, textDirection: TextDirection.ltr, )..layout(maxWidth: maxWidth); final exceeded = painter.didExceedMaxLines; painter.dispose(); if (exceeded) { high = mid; } else { low = mid + 1; } } return widget.text.substring(0, low) + '…'; } @override Widget build(BuildContext context) { return LayoutBuilder( builder: (context, constraints) { _truncated = _computeTruncatedText(constraints.maxWidth); return Column( crossAxisAlignment: CrossAxisAlignment.start, children: [ Text( _expanded ? widget.text : (_truncated ?? widget.text), style: widget.style, ), if (_truncated != null) GestureDetector( onTap: () => setState(() => _expanded = !_expanded), child: Padding( padding: const EdgeInsets.only(top: 4), child: Text( _expanded ? '收起' : '展开', style: const TextStyle(color: Colors.blue), ), ), ), ], ); }, ); } }

这个实现有几个值得说的地方。

第一，为什么用二分而不是从尾部一个个字符减？因为TextPainter.layout本身是个相对重的操作，长文本如果逐个字符尝试，最坏情况要调几百次layout。二分能把次数压缩到几十次。

第二，为什么_truncated不在initState算？因为此时你拿不到父级传入的宽度约束，只有到LayoutBuilder里才能拿到实际宽度。依赖宽度变化时会自动重新计算，这个设计才是可靠的。

第三，包含emoji的字符串不能用substring直接截断，否则会把一个完整的四字节字符从中间劈开，出现乱码。生产环境建议用characters扩展包，按“用户感知字符”截断。这一点可以说是展开收起组件最常见的隐藏炸弹。

5. 交互与字体：文本选择、长按菜单和自定义字体加载

5.1 SelectableText与SelectionArea：什么时候用哪个

默认Text不可选择，长按只会触发手势或什么都没有。如果你需要让用户复制文本，两种方案：SelectableText和SelectionArea。

SelectableText是一个独立组件，类似Text但自带选择、复制、全选行为。它最大的问题是无法与普通Text在一个文本流里自由混排，比如你无法让一行里“前一段可选、后一段不可选”。另外SelectableText的实现与Text并不完全相同，在部分文本装饰样式上的表现有差异。

SelectionArea是Flutter 3.3之后引入的更通用方案。它本身是一个容器，包裹在任意子树外面，子树里所有常规Text都会变成可选择的，而且仍然保持原来的布局方式。看个例子：

SelectionArea( contextMenuBuilder: (context, selectableRegionState) { return AdaptiveTextSelectionToolbar.buttonItems( anchors: selectableRegionState.contextMenuAnchors, buttonItems: [ ContextMenuButtonItem( label: '复制', onPressed: selectableRegionState.copySelectedText, ), const ContextMenuButtonItem( label: '收藏', onPressed: _favoriteSelectedText, ), ], ); }, child: Text('这段文字可以被用户选择并复制'), )

如果你的需求只是“某段纯文本可以复制”，用SelectableText就够了。如果需求是“页面里一大段富文本里的部分文字可复制”，请直接用SelectionArea，灵活性高得多。

5.2 Text的命中区域与手势冲突问题

用GestureDetector包Text时，常见的现象是：明明包了，点击文字区域有时响应，有时不响应。这通常不是Text的问题，而是命中测试边界被其他组件挡住。

GestureDetector的behavior参数有三个值。默认的deferToChild会让命中区域完全由子组件决定，如果Text比较小或者被透明Container盖住，就点不到。想强制让整个区域都可点击，用：

GestureDetector( behavior: HitTestBehavior.opaque, onTap: () => print('click'), child: Text('点击区域是整个Text的约束范围'), )

HitTestBehavior.opaque会把整个组件自身变成一个不透明的命中目标，即使子组件没有内容或只有透明背景，也能响应点击。

还有一个容易忽略的点：把包了Text的GestureDetector放进ListView时，垂直拖动和点击长按会争抢手势。如果你的Text需要长按触发菜单，同时列表又要滚动，可以给GestureDetector配置onLongPressStart，而不是onLongPress，因为它允许你在长按开始时先拿到手势，不至于完全打断滚动手势的竞争。

5.3 自定义字体加载：assets配置、FontLoader与google_fonts的网络加载

Flutter加载本地字体最简单的方式是在pubspec.yaml里声明：

fonts: - family: WorkSans fonts: - asset: assets/fonts/WorkSans-Regular.ttf - asset: assets/fonts/WorkSans-Bold.ttf weight: 700

然后直接引用：

Text( 'Hello', style: TextStyle( fontFamily: 'WorkSans', fontWeight: FontWeight.w700, ), )

这里有个很容易踩的坑：修改了pubspec.yaml后，热重载不会刷新字体配置，必须重启App。另外weight必须和font文件实际对应，如果你用一个Regular字重文件去声明weight: 700，Flutter不会自动加粗，运行时只是用同一套字形渲染。

网络字体的加载需要用到FontLoader：

Future<void> loadNetworkFont() async { final response = await http.get(Uri.parse('https://example.com/font.ttf')); final bytes = ByteData.view(response.bodyBytes.buffer); final loader = FontLoader('MyNetworkFont') ..addFont(Future.value(bytes)); await loader.load(); }

加载完成之后，你可以通过setState或者直接依赖DefaultTextStyle刷新页面的Text。注意事项是：字体加载完成前如果已经渲染了Text，会先用fallback字体显示，加载完成后再替换，于是出现“文字闪烁/字形跳动”。在Flutter Web上这个问题尤其明显，因为Web字体本身是异步加载的，如果首帧就渲染大量Text，引擎启动慢的问题会和字体闪烁叠加在一起。我的一般做法是在App的启动阶段提前load字体，在等待期间保持启动页常驻，而不是先进入页面再让用户看到字体从默认字体“跳”成目标字体。

6. 我在真实项目里排查过的Text问题：症状、根因与解法

6.1 中英文混排导致的行高参差不齐

聊天列表是最典型的场景：一条消息里既有中文、英文又有数字，三者的字体不同，ascent和descent也不一致。结果是消息泡泡的高度忽大忽小，视觉上非常难受。

我的排查步骤是先把所有Text的样式统一，设置相同的fontFamilyFallback，然后给height设置一个固定倍数，比如1.25。这会让每一行文本被强制约束到相同高度，中英文混排的“毛刺感”基本消失。如果还不够，可以继续加：

textHeightBehavior: const TextHeightBehavior( applyHeightToFirstAscent: false, applyHeightToLastDescent: false, )

这个参数用来控制首行顶部和末行底部是否被行高影响。默认是true，所以有时候明明height设了，首行上方和末行下方还是多出一块空白，把这两个字段关掉后段落整体更紧凑。

6.2 List里长文本滚动的卡顿与优化

Feed流页面最容易出现“文字多了就卡”的现象。表面看是列表卡顿，实际上很多情况下与文本的重新布局有关。RenderParagraph在收到新的约束或文本内容变化时，会重新跑一遍文本布局。如果你的列表项里有一个很长的Text，并且父组件每次滚动都触发重建，这个Text就会反复工作。

优化手段按成本从低到高排列：

• 给ListView设置itemExtent，让列表项高度固定，减少布局不确定性。
• 用RepaintBoundary把每个列表项包起来，隔离重绘区域。
• 把Text尽量写成const，或者保证相同文案和样式时复用同一Widget实例。
• 如果列表项里包含“展开/收起”这类逻辑，把TextPainter的测量结果缓存起来，不要在滚动中重复计算。

另外一个背景知识：Flutter从3.16开始在iOS上默认启用Impeller渲染引擎，文本渲染从Skia切到了Impeller，某些场景下文字光栅化性能有所提升。如果你们团队还没有把渲染引擎切换到Impeller，遇到文本性能瓶颈时可以考虑在原生工程里做一次AB测试。文本布局本身依然是CPU侧的消耗，GPU引擎改变不了TextPainter.layout的成本，这一点别搞混。

6.3 字体加载相关的怪异现象：方块字、闪烁和不生效

“中文全部变成方块”的根因，99%是当前使用的字体不包含中文字形，且fontFamilyFallback里也没有可用字体。解决方法是给App的主题样式中加上系统中文字体回退，或者干脆不指定fontFamily。

“字体用了但好像没换过来”，先检查三件事：

1. pubspec.yaml的fonts配置缩进是否正确。YAML里fonts必须顶格，family和fonts的层级经常写错。
2. font文件的实际字重是否与weight声明匹配。如果你声明的weight: 600但字体文件本身是Regular，很多平台会直接忽略或显示异常。
3. 是否重启了App。新增字体配置热重载经常不生效，很多人卡在这里。

“文字闪烁/首帧字体跳动”，在Web端多是因为字体异步加载。建议在入口处先用FontLoader预加载，等await完成后再runApp，这个方案的代价是首屏启动会稍微变慢，但换来的是字体一致性和稳定排版，对Flutter Web这种引擎启动慢的场景反而更友好。

6.4 为什么某个Text没有跟随主题变色

暗黑模式是重灾区。你把一个Text的style.color写死成Colors.black，那它在暗黑模式下自然还是黑色。问题是很多人忘记了自己在某个公共样式里写死过color，于是反复查Theme配置。

排查顺序应该是：先全局搜索这个Text有没有显式传style；再确认style里的color是否为null；最后看组件的DefaultTextStyle有没有被上层覆盖。如果只是想让Text跟随主题，正确做法是不传color，或者传Theme.of(context).colorScheme.onSurface之类的主题色。如果是封装组件，尽量不要在内部强制覆盖color，而是在参数里保留color字段，让外面决定。

文本显示不符合预期时，我习惯先问自己三个问题：这个Text的样式是从哪一层继承来的？它实际使用的字体回退到了哪个字体？当前命中测试和手势竞争是否被其他组件干扰？沿着这三条线去排查，大部分Text问题都能在十分钟内定位，而且不会再做无用功。