企业官网建设流程全解析

做Cocos开发这么多年，我见过太多项目上线后还在被适配问题追着跑，新手机一出就乱套，横屏改竖屏界面直接飞出屏幕。说实话，CocosCreator3.8.2这套引擎在适配能力上已经比早期版本成熟太多，但大多数人还是只在编辑器里拖一拖Canvas，根本不知道背后的机制。这次我正好在3.8.2上整理了一套多分辨率适配方案，顺手把横竖屏自动翻转也一起做了，整个Demo跑下来不到5分钟就能复现，于是把它完整拆给你看。

这篇不是讲玄学适配，而是直接可抄作业的实操总结。你会搞清楚Canvas到底在干嘛、监听屏幕方向变化的正确姿势、以及怎么用一套代码同时应对手机和平板的横竖屏切换。文章里的Demo工程结构很轻，适合刚接触CocosCreator 3.x的人，也适合老手拿去核对一下自己的配置习惯。所有代码我都放在正文里，你照着建节点、粘贴脚本、选参数，就能跑出和截图一样的效果。

1. 多分辨率适配的核心思路：先搞懂Canvas在替你做什么

很多人在项目里放一个Canvas节点就完事，遇到问题第一反应是换分辨率策略，换过来换过去还是黑边，最后干脆把UI全用绝对坐标写死。这种思路从一开始就走偏了。适配的前提是理解引擎替你做了什么，以及哪些事引擎确实帮不了你。

1.1 设计分辨率、屏幕尺寸和分辨率策略的三角关系

先说三个最容易混淆的概念：设计分辨率、屏幕尺寸、分辨率策略。设计分辨率是你“画稿子”时用的坐标基准，Cocos Creator 3.8.2里默认是960x640左右，但绝大多数游戏项目会改成1280x720或者1620x768。屏幕尺寸就是设备真实显示的像素或逻辑分辨率，比如iPhone 15 Pro Max的430x932点，安卓平板可能是一块2560x1600。分辨率策略则决定了脚本口、设计分辨率和屏幕尺寸之间的换算关系。

假设你的设计分辨率是1280x720，屏幕是430x932，这个比例差了两倍多。引擎需要决定：是让画面上下砍掉一部分？还是整体缩放显示全貌留黑边？还是直接拉伸变形？对应在CocosCreator里就是几种策略：

引擎内部真正做的事就是通过Canvas组件把设计分辨率映射到屏幕上，再把这一帧画面交给Camera渲染。这个映射关系一旦确定，你放置的UI只要基于设计分辨率坐标，就能等比呈现。可问题也出在这里：设计分辨率只有一个，屏幕却千奇百怪。你的脑子必须随时转换：这个元素在某个更宽的屏幕上，应该靠左还是居中？在更高的屏幕上，应该贴底还是留出安全区？

1.2 3.8.2项目里的推荐配置：我在Demo里怎么设的

新建CocosCreator3.8.2项目后，我建议你先改两个地方：项目设置和场景里的Canvas组件。我个人的习惯是统一以FIXED_HEIGHT（固定高度）作为适配基准。为什么？因为绝大多数横屏游戏的角色、按钮、操作区都习惯布置在屏幕中部，上下两个方向留出变化空间，固定高度能让UI整体缩放稳定，宽度方向的空白用背景延伸或UI控件去自适应。

具体操作顺序是这样的：打开构建发布面板，在“项目设置->项目数据”里把设计分辨率设置成1280x720。然后在场景层级管理器中选中Canvas节点，检查它的“适配高度”和“适配宽度”两个勾选状态。在3.8.2中，Canvas组件上有一个“Resolution Policy”属性，默认是SHOW_ALL，我们要把它改成FIXED_HEIGHT，或者直接勾选“Fit Height”。你说依靠哪个？我习惯直接改Canvas组件，因为这样在编辑器预览时马上能看到效果，而项目设置里的是给构建用的默认值，两边要保持一致。

这里有个关键点：Canvas节点上还有一个Camera子节点，它的orthoHeight（正交高度）会随着分辨率策略变化。如果之后你把分辨率策略改成FIXED_WIDTH，Camera的orthoHeight会自动调整，但很多人的2D坐标错乱问题其实就出在没搞清楚Camera和UI层的从属关系。简单说，Camera的视野必须和Canvas的设计分辨率匹配，否则你看到的就是“节点和镜头错位”。保持默认关联即可，别手欠去拆开它们。

2. 横竖屏自动翻转：别让游戏卡在“方向”上

多分辨率适配只是解决了“同一方向下不同尺寸的兼容”，横竖屏切换则是另一个维度的问题。手机从横屏转竖屏，屏幕的宽高比直接颠倒，原来的适配策略可能瞬间从FIXED_HEIGHT的理想模式变成灾难现场。你必须主动监听变化，并且在布局层面做出响应。

2.1 监听到方向变化的正确姿势

CocosCreator 3.8.2并没有一个专门的“orientation change事件”挂在节点身上，但引擎的view对象会派发canvas-resize事件。不管是浏览器窗口被拖拽、手机旋转，还是安卓平板折叠屏幕，最终都会反映为画布尺寸变化，所以监听这个事件是最通用的做法。如果你只在网页平台上跑，监听window.resize技术上也行，但为了后续打包原生和桌面端，统一用view.on('canvas-resize')更省心。

事件挂载的时机最好在onLoad里，挂在根节点上。注意别挂在会被销毁的UI节点上，否则切场景时监听就丢了，方向一变又不响应了。我一般放在常驻的“根脚本”里，比如一个挂在Canvas节点上的AutoFit组件，只要游戏进程活着它就一直在。

import { _decorator, Component, view, sys } from 'cc'; const { ccclass } = _decorator; @ccclass('AutoFit') export class AutoFit extends Component { private isLandscape: boolean = true; onLoad() { this.isLandscape = this.checkLandscape(); this.applyLayout(this.isLandscape); view.on('canvas-resize', this.onCanvasResize, this); } onDestroy() { view.off('canvas-resize', this.onCanvasResize, this); } private onCanvasResize() { const nowLandscape = this.checkLandscape(); if (nowLandscape !== this.isLandscape) { this.isLandscape = nowLandscape; this.applyLayout(this.isLandscape); } this.applySafeArea(); } private checkLandscape(): boolean { const frameSize = view.getFrameSize(); return frameSize.width > frameSize.height; } private applyLayout(isLandscape: boolean) { // 切横屏或竖屏时的UI调整，下面会写 } private applySafeArea() { // 刘海屏安全区适配，下面会写 } }

这段代码里checkLandscape用宽高比判断方向，比用角度判断更可靠，因为在PC浏览器里旋转手机模拟器时，系统角度事件可能不触发，但尺寸一定会变。判断完方向之后，再按照当前方向去调整UI布局，这是下一步的工作。

2.2 切换布局的两种落地方式

方向翻转让你的UI需要“换一套排布逻辑”，实现方式有两条路：一种是改Widget组件的对齐属性，另一种是切换整套布局节点。第一种适合结构简单的页面，比如顶部标题、底部按钮，反向以后把顶部变成左侧、底部变成右侧，通过改变Widget的isAlignTop、isAlignBottom、isAlignLeft、isAlignRight就能实现。第二种适合复杂界面，横屏一套完整节点树，竖屏一套完整节点树，切换时控制active。

我平时做项目会优先用“Widget动态改对齐”的方案，因为代码可控性强，不会出现两套节点状态不同步的问题。拿常见的顶部返回按钮举例：横屏时它在屏幕左上角，竖屏时它应该回到左上角但往下挪一点，这时用Widget对齐左上角，再添加一个top偏移值，方向变化时改偏移就行。

private topButtonWidget: Widget = null; private applyLayout(isLandscape: boolean) { if (!this.topButtonWidget) { const topButton = this.node.getChildByName('TopButton'); this.topButtonWidget = topButton.getComponent(Widget); } this.topButtonWidget.isAlignTop = true; this.topButtonWidget.isAlignLeft = true; this.topButtonWidget.top = isLandscape ? 20 : 80; this.topButtonWidget.updateAlignment(); }

记得每次修改Widget参数后调用updateAlignment()，否则引擎不会立刻重算位置。这一步很多人漏掉，导致改了属性但UI纹丝不动，排查半天发现是没刷新对齐。如果你用UIOpacity或自定义脚本直接改position，就不用调这个方法，但Widget仍然是更省心的选择，因为它的百分比对齐能自动适应宽高变化。

3. 完整Demo的落地过程：从项目配置到运行验证

理论讲再多，不如直接看一个能跑的Demo。这里我整理的是一个极简但五脏俱全的示例：有一个顶部标题栏、一个中央内容背景、一个底部按钮组，横竖屏切换时它们会自动重新排布，同时自动处理刘海安全区域。整个Demo画布设计分辨率是1280x720，策略是FIXED_HEIGHT。

3.1 Demo的层级结构和组件设计

场景层级很清晰：

• Canvas
  • Root（空节点，挂AutoFit脚本）
    • TopBar
    • ContentPanel
    • ButtonGroup
  • Camera

为什么要把自适应逻辑挂在一个空节点而不是直接挂Canvas？因为Canvas节点本身带有专门的适配逻辑，我们不要在它上面堆业务代码，Root作为根容器往后还能继续挂各种UI管理脚本，层次更干净。TopBar、ContentPanel、ButtonGroup这三个节点都用Widget做了基础对齐：TopBar对齐顶部并且左右撑满，ContentPanel居中并且宽高百分比，ButtonGroup对齐底部。

这套结构的好处是：横竖屏切换时，只要在AutoFit里调整它们的Widget偏移，整棵节点树就跟着动了。如果某个界面实在复杂，你也可以把三个子节点当作“横屏容器”和“竖屏容器”的替换目标，但Demo先保持最简结构，让逻辑好对照。

3.2 关键实现：AutoFit根节点脚本逐段讲解

完整脚本就是我在2.1节给的骨架，再补上两个具体方法。这里我说一下核心逻辑的推演过程。

先看设计分辨率1280x720，FIXED_HEIGHT策略下，屏幕高度始终对应720个设计单位，宽度会变。比如一块430x932的手机竖屏，屏幕宽度430，高度932，因为高度固定对应720，宽度按比例算出来是430 / 932 * 720 ≈ 332。这个数字远小于1280，意味着原本横屏布局里的左右区域都会跑到屏幕外。所以方向变化时，除了调整对齐方式，还要把能够拉伸的UI组件改成“从屏幕边缘对齐”，而不是“从中心向两边延伸”。

我把ContentPanel做成一个背景块，横屏时向左向右各留20%余量，竖屏时改成铺满屏幕且上下各留10%。实现如下：

private applyUIState(isLandscape: boolean) { const contentPanel = this.node.getChildByName('ContentPanel'); const contentWidget = contentPanel.getComponent(Widget); if (isLandscape) { contentWidget.isAlignLeft = true; contentWidget.isAlignRight = true; contentWidget.isAlignTop = true; contentWidget.isAlignBottom = true; contentWidget.left = 120; contentWidget.right = 120; contentWidget.top = 80; contentWidget.bottom = 80; } else { contentWidget.isAlignLeft = true; contentWidget.isAlignRight = true; contentWidget.isAlignTop = true; contentWidget.isAlignBottom = true; contentWidget.left = 40; contentWidget.right = 40; contentWidget.top = 120; contentWidget.bottom = 120; } contentWidget.updateAlignment(); }

按钮组和标题栏同理。标题栏本来就靠上，横屏时控件在左右两侧，竖屏时控件收到中间区域并缩小间距；按钮组横屏时对齐底部两侧，竖屏时变成纵向排列。为了Demo可读性，我直接在脚本里用active切了两套按钮子节点，一套是横向排列，一套是纵向排列，这只是演示，生产环境你按自己的UI结构决定用哪种方案。

安全区域的处理也很重要。iPhone的刘海屏和安卓挖孔屏会让部分屏幕区域不适合显示交互元素。CocosCreator 3.8.2里可以直接用sys.getSafeAreaRect()拿到安全区域，然后把它换算到设计分辨率坐标系下，再给Root容器设置一个安全边距。需要注意getSafeAreaRect()返回的是屏幕像素区域，要除以屏幕和设计分辨率之间的缩放比例才能用。最省事的方法是把安全区矩形的宽高直接用来约束Root节点的尺寸，核心代码如下：

private applySafeArea() { const safeRect = sys.getSafeAreaRect(); const frameSize = view.getFrameSize(); const scaleX = view.getVisibleSize().width / frameSize.width; const scaleY = view.getVisibleSize().height / frameSize.height; const designSafeWidth = safeRect.width * scaleX; const designSafeHeight = safeRect.height * scaleY; const root = this.node.getChildByName('Root'); const rootTransform = root.getComponent(UITransform); rootTransform.setContentSize(designSafeWidth, designSafeHeight); }

这段逻辑拿到真实屏幕安全区后，把它映射到设计分辨率下的宽高，然后把Root的大小限制在安全区内。如果你的UI全都挂在Root下面，并且按钮都基于Root边缘做百分比或Widget对齐，那么任何刘海屏都不会挡到关键操作。

3.3 编辑器预览与真机打包的验证要点

在编辑器和浏览器里模拟方向切换，很多项目就是一跑起来能看到效果，一打包就翻车，问题多半出在预览方式和浏览器壳的差异上。编辑器右上角有分辨率模拟器，可以直接切到竖屏尺寸，这会触发canvas-resize，AutoFit脚本能实时响应。这一步一定要做，而且要用几组不同比例测，比如1280x720、720x1280、1170x2532、820x1180。

构建预览时我一般选择“浏览器预览”，因为能看到控制台日志，适配逻辑出问题方便调。调好后打包Android或iOS再用真机验证。真机验证最容易忽略的点是“折叠屏”和“横屏锁定”：有些安卓手机会自动锁定方向，你怎么转它都不翻转，别急着改代码，先在系统设置里确认自动旋转打开了。

还有一点，原生平台的画布尺寸更新时机和网页不一样，个别机型会等动画结束后才触发resize。防御办法是在onLoad里先执行一次applyLayout和applySafeArea，再延迟200毫秒执行第二次，确保初始数据正确。

4. 常见问题与排查技巧实录

这节我把实际跑Demo时容易踩的坑都列出来，并且给出排查方向。适配代码本身不长，但环境差异带来的表现很多，能快速定位问题比背代码重要得多。

4.1 不触发resize、黑边、模糊怎么办

不触发canvas-resize通常是监听挂错地方或者被释放了。如果你把监听挂在某个普通节点上，节点在场景切换时被销毁，监听随着丢失。解决方法是把监听放到常驻节点上，或者用game.on等全局机制。另外一种可能是你用了iframe嵌入Web页面，外层iframe尺寸变了但内层画布没有跟随，这时需要手动调用view.resizeWithBrowserSize(true)并同时勾选项目设置里的“适配浏览器窗口”。

黑边问题我反复强调过，根源是适配策略用了SHOW_ALL，屏幕比例不匹配时为了保证完整显示，必然留边。想彻底消除黑边，要么用FIXED_HEIGHT/FIXED_WIDTH把基准固定在某一维，要么用NO_BORDER接受裁切。但要警惕，FIXED_HEIGHT不是万能的，如果你的UI左右元素真的不可裁剪，屏幕太宽时还是会出界。这时候配合Widget的百分比对齐，把关键内容都钉在安全范围内，背景用一块可拉伸的大图。

模糊问题一半原因出在图片资源本身不是2的幂尺寸，另一半出在“设计分辨率和你屏幕分辨率之间不是整数倍缩放”。比如设计分辨率1280x720，屏幕实际像素1920x1080，缩放比例1.5，引擎插值后文字会轻微发虚。解决方法是尽量让美术资源按设计分辨率整数倍输出，或者使用位图字体和Label的EnableBold合理搭配。测试时也别总用相同比例屏幕，换几台不同机型的真机感受最直观。

4.2 刘海屏和Android显示屏凹口的适配

sys.getSafeAreaRect()拿到的安全区在绝大多数iOS和安卓设备上都能正确返回，但它有个边界情况：安卓系统如果开启了导航栏手势，安全区底部会变化，而且这个变化是动态的。你在竖屏状态下得到的底部高度是32，横屏时可能变成48，所以必须在每次canvas-resize时都重新调用applySafeArea()，不能只在方向切换时算一次。

还有一类安卓机型是“超窄边框”或者“瀑布屏”，系统安全区可能返回0，这时候就要做兜底：判断安全区宽高和屏幕尺寸一致时，手动按照固定比例设置UI边距，不要在UI上堆太多关键元素。我的经验是，底部导航高度至少预留设备屏幕高度的3%，顶部预留5%左右，这样即使安全区数据缺失，界面也不至于失控。

4.3 我的避坑清单

这张表是我在多个项目里沉淀出来的，不是从一个Demo里现总结的。你可以把它当作一份“适配自检清单”贴在墙上。

写在后面的一点个人体会

适配这件事，代码本身不复杂，复杂的是你愿不愿意站在不同屏幕的角度去重新审视自己的UI结构。我在刚接触多分辨率时，也试图用一个分辨率策略套所有游戏，结果被各种黑边和裁切问题按在地上反复摩擦。后来才明白，好的适配是“从设计阶段就开始布局”，而不是等发布前再来打补丁。这套Demo最大的价值不是给你一段能用的脚本，而是让你看清：设计分辨率、Widget、安全区、方向事件这四件事是怎么串起来的。

最后再分享一个小技巧：在编辑器里预览时，改用“自定义分辨率模式”，把尺寸填成720x1280，再切回1280x720，来回多切几次，就能在几秒钟内模拟出绝大多数玩家的真实体验。很多看着唬人的适配问题，其实根本不用上真机，在这一个步骤里就能暴露干净。希望这篇内容能让你少走点弯路，如果Demo跑通了，记得把它扩展成你自己项目的基础模板，以后做新游戏会省下大把时间。