1. 项目概述一个困扰无数开发者的“口口”难题如果你是一名Unity开发者并且正在或准备开发微信小游戏那么“中文显示为‘口口’俗称豆腐块”这个问题你大概率已经遇到过或者即将遇到。这几乎是Unity项目发布到微信小游戏平台的一个“成人礼”。当你在Unity编辑器中看到完美显示的中文打包成WebGL并上传到微信开发者工具后却发现所有中文都变成了一个个方框那种挫败感相信很多同行都深有体会。这个问题背后的核心原因是字体缺失。在桌面或移动端原生平台Unity可以使用系统字体或动态字体Dynamic Font引擎会自动从运行环境中查找并加载所需的字形。然而微信小游戏本质上是一个基于浏览器内核的封闭运行环境其安全策略和资源加载机制与标准WebGL或原生平台有显著差异。平台不会提供完整的中文字体文件而动态字体在默认情况下又无法正确地从网络加载字体源。这就导致了当Unity尝试渲染一个中文字符时在目标字体中找不到对应的字形数据于是就用一个“缺失字形”的占位符通常是方框或问号来替代也就是我们看到的“口口”。解决这个问题的正统且最可靠的方法就是使用Unity的“Custom Set”功能来制作静态字体集。简单来说就是把你的游戏里所有需要用到的中文字符提前“烘焙”到一个字体文件里。这个文件会包含且仅包含这些指定的字符从而确保在微信小游戏环境中这些字符100%能被找到和渲染。本文将手把手带你走通整个流程从原理理解到工具实操最后还会分享一个我自用的、能极大提升效率的“自动扫描脚本”帮你一键收集项目中所有中文文本彻底告别手动整理的繁琐。2. 核心原理动态字体与静态字体的博弈要根治“口口”问题必须理解Unity字体渲染的两种模式动态字体Dynamic Font和静态字体Static Font。它们在资源处理、运行机制和平台兼容性上有着天壤之别。2.1 动态字体为何在微信小游戏上“失灵”动态字体是Unity的默认推荐选项尤其是对于TextMeshProTMP组件。它的工作原理很“智能”在运行时当需要渲染某个字符时Unity会向字体资源请求该字符的字形信息。如果该字体文件如一个.ttf或.otf文件中包含了这个字形就直接使用如果没有Unity会尝试从操作系统或指定的后备字体Fallback中查找。在桌面或移动端App中这个机制运作良好因为系统字体库非常庞大。但在微信小游戏环境下这个机制就崩溃了封闭的沙箱环境微信小游戏的运行环境是一个高度定制和封闭的浏览器内核它不提供也不允许游戏随意访问宿主系统即用户的手机的完整字体库。你无法指望它像PC上的Chrome一样拥有“宋体”、“微软雅黑”等字体。字体文件加载限制你可以将字体文件如msyh.ttf作为资源打包进项目。动态字体理论上可以引用这个文件。但问题在于微信小游戏平台对网络请求和外部资源加载有严格的同源策略和权限控制。Unity动态字体内部加载字形数据的机制可能与微信小游戏环境下的网络请求或文件读取API不兼容导致字体文件虽然存在但引擎在运行时却无法成功从中解析出字形。AOT编译限制微信小游戏使用JavaScript作为运行语言通过IL2CPP转换其AOTAhead-Of-Time编译特性使得一些在编辑器或原生平台可行的反射或动态资源加载方式变得不可预测。因此依赖运行时动态查询的字体方案在微信小游戏平台变得极不可靠。“口口”的出现就是动态查询失败后的统一表现。2.2 静态字体Custom Set的救赎之道静态字体顾名思义就是将字体“静态化”。我们不再依赖运行时的动态查找而是在构建Build阶段就明确告诉Unity“我的游戏里只会用到这些字符请把它们从源字体文件中提取出来生成一个只包含这些字符的新字体文件。”这个“明确告诉”的过程就是设置“Custom Set”。你可以在这个输入框里填入所有你需要用到的字符例如“玩家等级提升至恭喜获得金币”。Unity在构建时会扫描你填入的字符集从你指定的源字体如一个雅黑.ttf文件中将这些字符对应的字形轮廓信息通常是矢量路径抽取出来打包进最终的游戏资源中。这样做带来的决定性优势确定性打包进去的字形是百分百存在的。运行时渲染时引擎直接从这份打包好的、精简的字形数据中读取无需任何外部查询彻底规避了平台兼容性问题。资源可控一个完整的中文字体文件如思源黑体可能包含数万个汉字体积高达数MB甚至十几MB。通过Custom Set你可以将字体文件体积缩小到几十KB只包含游戏实际用到的几百个汉字这对于小游戏包体优化至关重要。兼容性满分因为所有渲染所需数据都已内嵌所以无论发布到微信、抖音小游戏还是其他任何对字体支持有限的HTML5平台显示效果都是一致的。注意静态字体最大的限制在于“静态”。如果你在游戏运行时通过代码动态生成了一个不在Custom Set列表里的新字符比如从服务器拉取了一个新的玩家昵称“魑魅魍魉”那么这个字符依然会显示为“口口”因为它的字形没有被提前打包进去。因此静态字体方案要求你对游戏内所有可能的文本内容有完全的预见和控制。3. 实战一步步创建并配置静态字体理解了原理我们开始动手。这里以Unity内置的UI Text组件和更现代的TextMeshProTMP组件分别说明因为两者的配置流程有差异。我强烈推荐在新项目中使用TextMeshPro它功能更强大渲染效果更好。3.1 为传统UI Text配置静态字体如果你的项目还在使用旧的Unity UI系统UnityEngine.UI.Text配置步骤如下准备源字体文件首先你需要一个包含你所需中文字形的.ttf或.otf字体文件。确保你有该字体的使用授权。将字体文件拖入Unity项目的Assets目录下例如Assets/Fonts/MyChineseFont.ttf。创建字体材质和纹理在Project窗口选中该字体文件在Inspector面板中你需要进行关键设置Font Size建议设置一个足够大的值如80。这个值会影响生成的字体纹理质量。值越大纹理越清晰但体积也越大。对于小游戏80是一个在清晰度和体积间比较平衡的起点。Rendering Mode选择Smooth。Character从下拉菜单选择Custom Set。Custom Chars这是核心将你需要打包的所有字符粘贴进这个文本框。例如你可以先粘贴“开始游戏设置音效金币钻石”。先别急后面我们会用脚本自动收集。应用并生成点击Inspector面板底部的Apply按钮。Unity会根据你设置的Font Size和Custom Chars从源字体中提取字形并生成一个字体纹理通常是一个.png文件和一个对应的材质球。这个过程可能会花费几秒到几十秒取决于字符数量。在UI Text组件中使用创建一个UI Text对象在其Font属性中选择你刚刚处理过的这个字体资源例如MyChineseFont而不是原始的.ttf文件。此时该Text组件将只显示你预设的字符集内的文字。3.2 为TextMeshProTMP配置静态字体TMP是更优的选择它使用Signed Distance FieldSDF技术字体放大后边缘依然平滑。配置流程类似但界面不同准备源字体与生成TMP字体资源同样将源字体文件如.ttf放入项目。打开Window TextMeshPro Font Asset Creator窗口。Source Font File选择你的中文字体文件。Sampling Point Size相当于UI Text的Font Size推荐80-120。Atlas Resolution字体纹理图集的大小例如1024x1024。如果字符很多可能需要2048x2048。Character Set这是关键选择Custom Characters。Custom Character List将你的字符集粘贴到这里。生成与保存点击右下角的Generate Font Atlas按钮。预览窗口会显示生成的SDF纹理。确认无误后点击Save或Save as...将其保存为一个TMP Font Asset文件例如MyChineseFont_SDF.asset。在TMP组件中使用在TMP Text组件的Font Asset属性中选择你刚刚创建的MyChineseFont_SDF资源。实操心得对于TMPSampling Point Size和Atlas Resolution需要权衡。点尺寸越大SDF数据越精细抗锯齿效果越好但纹理体积也越大。1024x1024的图集大约能容纳1000-2000个常用汉字取决于点尺寸对于大多数小游戏的主界面文字已经足够。如果包含大量剧情文本可能需要增大图集或分割成多个字体资源。4. 效率革命自动扫描项目中文文本脚本手动收集和维护Custom Set字符列表是极其痛苦且容易出错的。游戏中有多少UI多少配置表多少本地化文件漏掉一个运行时就是“口口”。为此我编写了一个C#编辑器脚本它可以自动扫描整个项目或指定目录中所有可能包含文本的资源并提取出所有中文字符。4.1 脚本核心思路与实现这个脚本的核心是使用正则表达式匹配中文字符Unicode范围\u4e00-\u9fff并递归遍历指定目录下的文件。它需要处理多种资源类型场景文件.unity解析场景中的GameObject查找所有Text和TMP_Text组件读取其text属性。预制体文件.prefab同样加载预制体并查找其中的文本组件。脚本文件.cs扫描代码中所有字符串常量用双引号包裹的部分提取中文。文本配置文件如.json, .txt, .xml, .csv等直接读取文件内容进行匹配。ScriptableObject资产.asset通过反射尝试读取其可序列化字段中的字符串值这是一个进阶功能需要小心处理。下面是一个简化但功能强大的核心扫描方法示例using UnityEngine; using UnityEditor; using System.IO; using System.Text; using System.Text.RegularExpressions; using System.Collections.Generic; public class ChineseTextScanner : EditorWindow { private string targetFolderPath Assets; private HashSetchar collectedChars new HashSetchar(); private string customSetString ; // 匹配中文字符的正则表达式包括基本汉字和扩展区 private static Regex chineseRegex new Regex([\u4e00-\u9fff\u3400-\u4dbf\U00020000-\U0002A6DF\U0002A700-\U0002B73F\U0002B740-\U0002B81F\U0002B820-\U0002CEAF]); [MenuItem(Tools/扫描项目中文文本)] static void Init() { GetWindowChineseTextScanner(中文文本扫描器).Show(); } void OnGUI() { GUILayout.Label(扫描设置, EditorStyles.boldLabel); targetFolderPath EditorGUILayout.TextField(扫描目录:, targetFolderPath); if (GUILayout.Button(开始扫描)) { ScanProject(); } if (collectedChars.Count 0) { GUILayout.Space(10); GUILayout.Label($已找到 {collectedChars.Count} 个不重复的中文字符, EditorStyles.boldLabel); customSetString new string(collectedChars.ToArray()); EditorGUILayout.TextArea(customSetString, GUILayout.Height(100)); if (GUILayout.Button(复制到剪贴板)) { GUIUtility.systemCopyBuffer customSetString; EditorUtility.DisplayDialog(完成, $已复制 {collectedChars.Count} 个字符到剪贴板, OK); } } } void ScanProject() { collectedChars.Clear(); customSetString ; // 1. 扫描场景文件 string[] sceneGuids AssetDatabase.FindAssets(t:Scene, new[] { targetFolderPath }); foreach (string guid in sceneGuids) { string path AssetDatabase.GUIDToAssetPath(guid); ExtractChineseFromScene(path); } // 2. 扫描预制体文件 string[] prefabGuids AssetDatabase.FindAssets(t:Prefab, new[] { targetFolderPath }); foreach (string guid in prefabGuids) { string path AssetDatabase.GUIDToAssetPath(guid); ExtractChineseFromPrefab(path); } // 3. 扫描脚本和文本文件简化示例实际需递归遍历目录 ProcessDirectory(new DirectoryInfo(targetFolderPath)); Debug.Log($扫描完成共找到 {collectedChars.Count} 个不重复的中文字符。); } void ExtractChineseFromScene(string scenePath) { // 注意直接解析.scene文件文本是复杂且易错的。 // 更稳健的方法是通过EditorSceneManager打开场景但不保存来获取对象。 // 这里为简化仅说明思路。实际脚本中我们使用第二种方法。 // 伪代码打开场景 - 遍历所有GameObject - 获取Text/TMP_Text组件 - 提取text } void ExtractChineseFromPrefab(string prefabPath) { // 使用PrefabUtility.LoadPrefabContents在不影响原文件的情况下加载预制体 GameObject prefabRoot PrefabUtility.LoadPrefabContents(prefabPath); TextComponent[] textComps prefabRoot.GetComponentsInChildrenTextComponent(true); TMP_Text[] tmpComps prefabRoot.GetComponentsInChildrenTMP_Text(true); foreach (var comp in textComps) AddTextToSet(comp.text); foreach (var comp in tmpComps) AddTextToSet(comp.text); PrefabUtility.UnloadPrefabContents(prefabRoot); } void ProcessDirectory(DirectoryInfo dir) { // 扫描.cs文件 foreach (FileInfo file in dir.GetFiles(*.cs)) { ExtractChineseFromTextFile(file.FullName); } // 扫描常见的文本配置文件 string[] textExtensions new[] { .txt, .json, .xml, .csv, .yaml, .yml }; foreach (FileInfo file in dir.GetFiles(*.*)) { if (System.Array.Exists(textExtensions, ext file.Extension.Equals(ext, System.StringComparison.OrdinalIgnoreCase))) { ExtractChineseFromTextFile(file.FullName); } } // 递归子目录 foreach (DirectoryInfo subDir in dir.GetDirectories()) { ProcessDirectory(subDir); } } void ExtractChineseFromTextFile(string filePath) { try { string content File.ReadAllText(filePath, Encoding.UTF8); MatchCollection matches chineseRegex.Matches(content); foreach (Match match in matches) { AddTextToSet(match.Value); } } catch (System.Exception e) { Debug.LogWarning($读取文件 {filePath} 时出错: {e.Message}); } } void AddTextToSet(string text) { if (string.IsNullOrEmpty(text)) return; MatchCollection matches chineseRegex.Matches(text); foreach (Match match in matches) { foreach (char c in match.Value) { collectedChars.Add(c); } } } }4.2 脚本使用流程与注意事项创建脚本在项目的Assets/Editor目录下如果没有就创建一个新建一个C#脚本将上述代码逻辑需补充完整场景扫描部分写入。打开窗口在Unity编辑器顶部菜单栏点击Tools 扫描项目中文文本。设置路径在弹出窗口中指定你要扫描的目录默认为Assets扫描整个项目。执行扫描点击“开始扫描”按钮。脚本将遍历场景、预制体、代码和配置文件这个过程可能需要几十秒到几分钟取决于项目大小。获取结果扫描完成后窗口会显示找到的不重复中文字符数量并将所有字符拼接成一个字符串显示在文本框中。一键复制点击“复制到剪贴板”按钮这个超长的字符串就被复制了。粘贴到Custom Set打开你的字体设置UI Text或TMP Font Asset Creator将剪贴板内容粘贴到Custom Chars或Custom Character List输入框中。注意事项与避坑指南性能考虑首次全项目扫描可能较慢。建议在项目文本内容相对稳定后如主要功能开发完成时运行或分模块扫描。动态文本处理此脚本无法捕获运行时通过代码拼接、从服务器加载的文本。对于这部分内容你需要手动将可能出现的字符范围例如玩家昵称常用汉字、物品名称字典补充到Custom Set中。字体文件授权务必确保你使用的源字体文件允许嵌入和分发。许多商业字体如微软雅黑的许可协议禁止嵌入软件或网页中。推荐使用开源字体如思源黑体Source Han Sans、站酷系列字体或阿里巴巴普惠体它们都提供了明确的OFL等开源协议允许免费商用和嵌入。字符集完整性扫描脚本提取的是“已存在”的文本。请确保你的测试用例覆盖了游戏所有界面和流程包括错误提示、加载提示等容易被忽略的地方。5. 高级技巧与包体优化策略解决了显示问题我们还要考虑性能与包体。一个包含3000个汉字的静态字体纹理如果设置不当可能会占用数MB的空间。5.1 字体纹理图集优化合理设置图集尺寸Atlas Resolution从512x512开始尝试。在TMP Font Asset Creator中生成后查看预览图。如果字符排列紧凑没有大量空白说明尺寸合适。如果字符挤在一起或提示图集已满则需要增大尺寸。目标是使用能满足需求的最小尺寸。调整采样点大小Sampling Point Size这个值直接影响SDF数据的质量和纹理的清晰度。对于小游戏在72-96之间通常能获得不错的显示效果。你可以做一个对比测试用72和120分别生成字体在游戏里放大文字观察边缘如果差异不明显就选择更小的值。分割字体资源不要试图把所有文字塞进一个字体资源。可以按功能模块拆分Font_UI_Main.asset主界面、通用按钮文字字符数少可高质量。Font_Dialog.asset剧情对话文字字符数多可适当降低质量。Font_System.asset系统提示、日志仅包含数字、字母和少量中文。 这样可以根据不同用途独立优化也便于管理。5.2 应对动态文本的混合方案对于完全不可预知的动态文本如实时聊天、用户自定义名称纯静态字体无能为力。此时需要混合方案动态字体兜底为处理动态文本的UI组件单独配置一个动态字体。并确保将这个动态字体所需的.ttf文件打包进StreamingAssets或Resources目录具体路径需测试微信小游戏平台的加载兼容性。同时设置好Fallback字体链指向你的主静态字体。这样当动态字体找不到字形时会尝试从后备字体中查找而你的静态字体可以作为第一后备。服务端字形图片对于极端情况如生僻字一种折中方案是在服务端将文本渲染成图片下发给客户端显示。但这会带来网络请求和图片加载的开销仅作为最后手段。预加载字符集如果动态文本的范围是可枚举的比如所有可能的道具名称可以在游戏启动时将这些字符主动添加到字体资源的“动态补充”列表中部分字体插件支持此功能或者直接将其包含在初始Custom Set中。5.3 微信小游戏平台特殊配置检查即使字体配置正确微信小游戏平台本身的一些设置也可能导致问题CDN与域名白名单如果你将字体文件放在远程CDN务必在微信小游戏后台的“开发设置”中将CDN域名添加到downloadFile合法域名列表中。文件后缀与MIME类型确保服务器对.ttf、.otf、.woff等字体文件返回正确的MIME类型如font/ttf,application/font-woff。构建后真机测试在微信开发者工具中预览无误后必须使用真机预览功能进行测试。微信开发者工具的环境与真机特别是iOS和不同型号的Android手机可能存在细微差异真机测试是最终验证环节。6. 常见问题排查与解决方案实录即使按照步骤操作你可能还是会遇到一些棘手的情况。下面是我在实际项目中踩过坑后总结的排查清单问题现象可能原因排查步骤与解决方案编辑器正常微信小游戏上仍显示“口口”1. Custom Set字符集不完整漏掉了某些文本。2. 字体资源未正确打包或加载。3. 使用了动态字体且后备字体失效。1.检查字符集使用扫描脚本重新扫描并与已配置的字符集对比。检查运行时动态生成的文本。2.检查构建结果使用微信开发者工具的“代码依赖分析”或查看构建日志确认字体纹理/资产文件是否在包体内。3.检查字体引用确认UI组件引用的字体资源是处理过的静态字体Asset而不是原始的.ttf文件。字体边缘模糊、有锯齿1. 静态字体生成时Sampling Point Size设置过低。2. 纹理图集Atlas Resolution尺寸太小导致字形被过度压缩。1.提高采样点大小在Font Asset Creator中将Sampling Point Size从72提高到96或120重新生成。2.增大图集尺寸如果图集预览很满尝试增大Atlas Resolution。3.检查SDF生成质量TMP的SDF生成模式如SDF32、SDFAA也会影响质量尝试更换模式。包体体积异常增大字体纹理图集过大或包含了过多不必要的字符。1.精简字符集再次审核Custom Set移除测试用的、未使用的字符。2.优化图集参数尝试降低Sampling Point Size使用刚好够用的Atlas Resolution。3.分割字体将字体按模块拆分避免一个巨大的字体资源包含所有字符。部分字符在真机上不显示1. 真机系统字体与编辑器环境不同动态字体后备查找失败。2. 生僻字不在Custom Set中。1.强制使用静态字体对于关键UI确保全部使用Custom Set静态字体。2.扩展字符集将真机测试中发现缺失的字符加入Custom Set。3.检查字体授权确认源字体文件本身包含该生僻字。文本渲染性能下降使用了过多不同字号或样式的静态字体实例导致Draw Call增加。1.合并字体材质尽量让不同UI文本共享同一个字体材质/Asset。2.使用TMP的Font Asset Variant对于粗体、斜体等变体使用TMP的Font Asset Variant功能它们可以共享同一个纹理图集减少Draw Call。最后分享一个我个人的小技巧在项目的README或一个专门的配置文档里维护一个“字体使用规范”。明确记录项目主字体、备用字体、各字体Asset的字符集范围和用途。当有新文本需要加入时先运行扫描脚本更新字符集然后重新生成字体Asset并更新文档。这个习惯虽然前期有点麻烦但对于团队协作和项目长期维护来说能省去大量排查“口口”问题的时间。字体问题一旦在后期爆发修改和测试成本会非常高因此前期建立可靠的流程至关重要。