配置里已经写了 Skyline,真机上卡片却挤成一排、页面滑不动,或者部分组件直接不能用------这多半不是「引擎坏了」,而是当前页其实还跑在 WebView 上,默认布局和盒模型跟旧页不一样,或把页面级滚动、position sticky 原样搬了过来。下面按「先分清配置写了、真机仍是 WebView、样式乱不是同一件事 / 先确认当前页是不是真的跑在 Skyline 上 / 样式全乱要先对齐默认布局和盒模型 / 滚动和组件兼容按页灰度,不兼容的先留在 WebView / 上线前核对双端对比、滚动、返回和回退」来接。
1. 先分清:配置写了 Skyline、真机还在用 WebView、样式乱不是同一件事
不要一看到布局错位,就把全局 renderer 改回 WebView,也不要在还没确认渲染后端的时候,先大改一版样式。先分清三种情况:
- 配置写了,但当前运行环境并没有用 Skyline。基础库不够、客户端版本不够、命中了关闭 Skyline 的 AB 实验,或开发者工具里把快捷切换入口设成了强制 WebView,页面仍按旧引擎画。这时改 WXSS 对不齐是正常的,因为你改的是「以为在 Skyline 上」的样式,真机看到的却是另一套。
- 确实跑在 Skyline 上,但默认布局、盒模型和旧页不一样 。Skyline 里节点默认
display是flex,box-sizing默认是border-box,跟 WebView 常见的block+content-box不是同一套假设。以前靠块级元素自动撑满一行的写法,会变成挤在一行或高度被吞掉。 - 样式本身能用,但滚动和定位机制不同 。Skyline 不支持用
overflow: scroll做滚动,页面级滚动也和旧页不是同一条路径,要用scroll-view;position: sticky更稳妥的做法是换成sticky-header/sticky-section。看起来「滑不动、吸顶失效、组件不能用」,往往是把旧页的滚动和定位原样搬过来了。
更稳的分工是:先确认「这一页此刻是不是 Skyline」,再决定改配置还是改样式。不要用开发者工具的模拟器结果代替真机,也不要在首页、订单、支付这类关键链路上先全量切过去。同一小程序里可以按页面选择渲染后端,WebView 页面和 Skyline 页面允许共存,这正好用来做灰度,而不是一刀切。
Skyline 还依赖按需注入和 glass-easel 组件框架。只写了 renderer,却没有配套的 lazyCodeLoading 和 componentFramework,配置看起来「已经开了」,实际可能根本走不起来,或出现自定义组件方法找不到、首屏白一块的情况。按需注入本身也会改变组件注入时机,这和渲染引擎是两件事,要先单独验证,再叠加 Skyline。
2. 先确认当前页是不是真的跑在 Skyline 上
判断「开没开成功」,不要只看 json 里有没有 "renderer": "skyline",要在页面里读运行时信息。基础库 2.26.2 起可以用 wx.getSkylineInfoSync(低版本要先判是否存在)。它返回的是「当前运行环境支不支持」,不是「你写了配置就一定生效」。
js
function readSkylineInfo() {
if (typeof wx.getSkylineInfoSync !== 'function') {
return { isSupported: false, version: '', reason: 'api missing' }
}
try {
const info = wx.getSkylineInfoSync() || {}
return {
isSupported: !!info.isSupported,
version: info.version || '',
reason: info.reason || ''
}
} catch (err) {
return { isSupported: false, version: '', reason: 'throw' }
}
}
Page({
data: {
skylineOn: false,
skylineVersion: '',
skylineReason: ''
},
onLoad() {
const info = readSkylineInfo()
this.setData({
skylineOn: info.isSupported,
skylineVersion: info.version,
skylineReason: info.reason
})
if (!info.isSupported) {
console.warn('skyline not active', info.reason)
}
}
})
isSupported 为 false 时,重点看 reason:
client not supported或baselib not supported:当前微信客户端或基础库不够。按目前官方迁移说明,安卓和 iOS 需要微信 8.0.40 或以上、基础库 3.0.2 或以上,鸿蒙 OS 版本要求更高。不要只在开发者工具里验证通过就当成全量可用。a-b test not enabled:命中了分析平台上关闭 Skyline 的 AB 实验。配置里可以把rendererOptions.skyline.disableABTest设为true,避免一部分用户仍走 WebView、一部分走 Skyline,同样的页面却出现两种排版。SwitchRender option set to webview:本地调试的快捷切换入口被设成了强制 WebView。这只影响开发环境,不要据此判断正式版「开不了」。
支持情况确认之后,再把必要配置写全。只想在部分页面开启时,把 renderer 和 componentFramework 写在页面 json 里,不要一上来改全局默认后端。全局仍建议先补齐按需注入和渲染选项,让后续页面切换时少踩默认值差异。
json
{
"lazyCodeLoading": "requiredComponents",
"componentFramework": "glass-easel",
"rendererOptions": {
"skyline": {
"disableABTest": true,
"defaultDisplayBlock": true,
"defaultContentBox": true,
"tagNameStyleIsolation": "legacy",
"enableScrollViewAutoSize": true
}
}
}
页面 json 再单独打开渲染后端,并按后面两节处理滚动:
json
{
"renderer": "skyline",
"componentFramework": "glass-easel",
"disableScroll": true,
"navigationBarTitleText": "订单列表"
}
defaultDisplayBlock 和 defaultContentBox 是为了让 Skyline 的默认布局、盒模型尽量靠近旧的 WebView 习惯,减少「同样一份 WXSS,两边对不齐」。tagNameStyleIsolation 设成 legacy,是为了让标签选择器的匹配方式更接近旧页,避免全局 view、text 这类选择器突然不生效或作用范围变化。这些项没有写时,不要先怀疑是组件坏了。
还要注意:getSkylineInfoSync 说的是「环境支不支持」,页面最终用哪套后端,还取决于该页有没有声明 renderer,以及低版本回退。开发阶段建议在真机和开发者工具里都打一次日志,把 isSupported、version、reason 留下,再对比样式问题。
3. 样式全乱:先对齐默认布局和盒模型,再改具体规则
确认页面确实跑在 Skyline 上之后,再动手改样式。优先调整默认假设,而不是给每个节点加一长串补丁。
先处理默认 display。Skyline 默认是 flex,且 flex-direction 默认是 column。旧页里一个 view 常常被当成块级元素,子节点会上下排列、宽度撑满。切到 Skyline 后,如果没开启 defaultDisplayBlock,这些节点按弹性布局计算,宽、高、对齐方式都会变:并排的标签可能被拉成一列,本该撑满的卡片只剩内容宽度,或者子元素在交叉轴上被拉伸变形。全局打开 defaultDisplayBlock 后,再对真正需要弹性布局的容器显式写 display: flex。不要反过来:默认已经是 flex,却还在每个容器上补 display: block,两边的阅读成本都会变高。
再处理盒模型。Skyline 默认 box-sizing 是 border-box,WebView 常见默认是 content-box。同样写 width: 100% 再加 padding、border,两边算出来的占用宽度不一样,这就是「卡片溢出屏幕、两列网格对不齐」的常见来源。defaultContentBox 打开后,默认盒模型会回到更接近旧页的方式。无论选哪一种,同一套公共样式里不要混用两套假设。需要固定尺寸的按钮、标签,明确写上 box-sizing。
定位和滚动相关的样式不要照搬。overflow: scroll 在 Skyline 里不受支持,只能通过 scroll-view 做滚动;也不支持单独写 overflow-x / overflow-y。position: fixed 要从较新的客户端版本算起才支持,并且只相对窗口视口定位,不要假设它能相对某个父容器固定。z-index 不形成完整的层叠上下文,主要对兄弟节点生效,还不要写在 scroll-view 的直接子节点上指望它把内部图层抬起来。position: sticky 更稳妥的替换是 sticky-header、sticky-section,而不是继续调 top 碰运气。
选择器和重置也要收一收。Skyline 支持的 WXSS 是 WebView 的子集,不是超集。不支持的布局(例如完整的 inline、inline-block 用在普通 view 上)不要继续当常规手段。全局重置时,给常用标签补上 position: relative,并把 page 高度设为 100%,有利于后续用 scroll-view 撑满剩余空间。媒体查询目前主要用于暗黑模式,不要把整套响应式断点寄托在它上面。
css
page,
view,
text,
image,
button,
scroll-view,
swiper,
input,
textarea {
position: relative;
}
page {
height: 100%;
}
.list-page {
height: 100%;
display: flex;
flex-direction: column;
}
.list-scroll {
flex: 1;
min-height: 0;
}
改样式时建议左右对照:同一页在 WebView 和 Skyline 下各看一遍。差异如果集中在宽度被 padding 撑破、子元素挤成一行、吸顶失效,优先回到这一节的默认值,而不是给单个卡片写魔法数字。
4. 滚动对不上、组件不能用:用 scroll-view 做主滚动,按页灰度
Skyline 页把「整页跟着手指滑动」从页面级滚动换成 scroll-view 更稳。页面 json 里设 disableScroll: true,根节点用 flex 把导航、筛选和列表分区,中间的 scroll-view 负责滚动。高度必须明确:父级给它确定的剩余高度,或打开 enableScrollViewAutoSize 让它按内容/容器自动撑开。高度是 auto、父级又没有界限时,就会出现「内容很高却滑不动」「下拉刷新不触发」。
列表页优先让一个主 scroll-view 承担滚动,避免页面滚动和内部滚动抢手势。下拉刷新、上拉加载接到这个 scroll-view 的 refresher 和滚动事件上,不要同时指望页面级的 onPullDownRefresh、onReachBottom 还按旧页那样触发。需要吸顶的筛选条,放到 sticky-header 里,而不是对普通 view 写 position: sticky。
html
<view class="list-page">
<view class="filter-bar">{{filterLabel}}</view>
<scroll-view
class="list-scroll"
scroll-y
type="list"
refresher-enabled="{{true}}"
refresher-triggered="{{refreshing}}"
bindrefresherrefresh="onRefresh"
bindscrolltolower="onLoadMore"
>
<view wx:for="{{list}}" wx:key="id" class="card">{{item.title}}</view>
</scroll-view>
</view>
js
Page({
data: {
filterLabel: '全部',
refreshing: false,
list: [],
page: 1,
loadingMore: false,
noMore: false
},
onRefresh() {
this.setData({ refreshing: true, page: 1, noMore: false })
this.fetchList(1, true)
},
onLoadMore() {
if (this.data.loadingMore || this.data.noMore || this.data.refreshing) return
this.setData({ loadingMore: true })
this.fetchList(this.data.page + 1, false)
},
fetchList(page, replace) {
// 用自有请求替换;成功后再结束 refresher,失败也要停下
const done = (items) => {
const next = Array.isArray(items) ? items : []
const list = replace ? next : (this.data.list || []).concat(next)
this.setData({
list: list,
page: page,
refreshing: false,
loadingMore: false,
noMore: next.length === 0
})
}
const fail = () => {
this.setData({ refreshing: false, loadingMore: false })
}
this.requestList(page).then(done).catch(fail)
}
})
「部分组件不能用」不要先理解成整个引擎都不能上。更常见的是:某个基础组件在 Skyline 下的属性、样式或事件支持范围比 WebView 更窄,或者它依赖的是旧的页面滚动、层级和原生组件实现。处理顺序建议是:
- 先查这个组件在 Skyline 下的支持与差异,确认是完全不可用,还是某个属性、插槽、样式写法不生效。
- 能替换的就替换,例如滚动容器统一改
scroll-view,吸顶改官方吸顶组件,而不是继续用旧 CSS 技巧硬顶。 - 暂时无法对齐的页面,保留
"renderer": "webview",不要为了单个组件把已经稳定的 Skyline 页再改回去。 - 按页面灰度,先迁列表、内容展示这类结构简单的页,表单、地图、视频、支付结果页等涉及原生组件和复杂层级的,等对照过真机再迁。
自定义组件要跟 glass-easel 一起验证。旧的组件写法大多数能继续用,但样式隔离、标签选择器、部分生命周期时序可能有差别。不要把只在 WebView 页验证过的组件,直接放到 Skyline 页当「已经兼容」。组件库如果提供了 Skyline 适配说明,按页面逐步替换,不要混用两套布局假设。
5. 上线前核对:双端对比、滚动、返回、低版本回退
接口和配置接上之后,真正容易在真机上暴露的是「以为开了其实没开」和「只在开发者工具里看过」。建议把下面几条过一遍:
- 运行时信息 :在目标页打出
isSupported、version、reason。正式包里抽安卓、iOS 各看一次,不要只看开发者工具。若仍出现a-b test not enabled,确认disableABTest是否已生效。 - 双端对照 :同一页分别在 WebView 和 Skyline 下打开,核对卡片宽度、两列对齐、按钮高度、文字折行。差异如果来自默认
display或box-sizing,先改全局选项,再改单页补丁。 - 滚动 :内容超过一屏时必须能滑;下拉刷新能结束,不能卡在 loading;上拉加载不能重复请求。快速连滑、从详情返回列表,列表位置和加载状态不能乱。
scroll-view高度不足时先修高度,不要加延时重试去「激活」滚动。 - 吸顶与固定层 :筛选条吸顶是否还在;底部按钮、返回顶部是否挡内容;弹层能不能盖住列表。涉及
fixed、z-index、sticky的地方单独看安卓和 iOS。 - 返回与切页:Skyline 页跳到 WebView 页再返回,或反过来,页面栈、滚动位置、自定义导航栏要对得上。不要假设两种渲染后端共用完全相同的页面滚动恢复。
- 低版本回退 :客户端或基础库不够时,页面应能回到 WebView 并可用,而不是白屏或方法找不到。回退页不要依赖只在 Skyline 里才有的滚动结构;必要时用
getSkylineInfoSync分支不同的模板或提示更新。 - 按需注入叠加问题:如果白屏、方法找不到只在打开 Skyline 后出现,先单独关渲染后端、只留按需注入看能否复现。能复现就先按按需注入的方式修组件引用,再重新打开 Skyline。
- 关键链路灰度:首页、下单、支付、登录不要第一批全量切。先放访问量中等、结构清晰的列表或内容页,收集真机问题后再扩。
上线前还可以自问三句:这一页此刻是不是真的跑在 Skyline 上?样式问题是默认布局和盒模型不同,还是某条不支持的 CSS?滚动和吸顶有没有从页面级写法迁到 scroll-view 和官方吸顶组件?这三句都答得上,「样式全乱、滚动对不上、部分组件不能用」这三类问题大多能收住。
本文由 DEVDIY 整理,实际项目里先确认渲染后端,再对齐默认布局并用 scroll-view 接管滚动,比一上来全量改样式更省事。