Skyline JSON 配置规范
适用场景
- 创建新的 Skyline 小程序项目
- 从 WebView 迁移到 Skyline 渲染引擎
- 配置混合渲染（部分页面 Skyline、部分 WebView）
- 配置 rendererOptions 优化样式兼容性
- 排查 Skyline 配置相关的编译错误
核心概念
三级配置层次
| 层级 | 文件 | 作用 | 关键配置 |
|---|
| 全局 | app.json | 全局启用 Skyline | renderer, componentFramework, rendererOptions |
| 页面 | 页面.json | 页面级配置/覆盖 | navigationStyle, disableScroll, renderer |
| 工具 | project.config.json | 开发者工具调试 | setting.skylineRenderEnable |
最小必需配置
// app.json
{
"renderer": "skyline",
"componentFramework": "glass-easel",
"lazyCodeLoading": "requiredComponents"
}
// 每个页面的 .json
{
"navigationStyle": "custom"
}
文档索引
根据需求快速定位（路径相对于 references/）：
| 我想要... | 查阅文档 |
|---|
| 了解 app.json 中所有 Skyline 相关配置 | app-config.md |
| 了解页面级配置和混合渲染 | page-config.md |
| 配置开发者工具 | project-config.md |
| 查看完整配置模板 | patterns.md |
强制规则
MUST（必须遵守）
- app.json 必须包含三项必需配置：
// ❌ 错误：缺少 componentFramework 和 lazyCodeLoading {"pages": ["pages/index/index"], "renderer": "skyline"} // ✅ 正确：三项缺一不可 {"renderer": "skyline", "componentFramework": "glass-easel", "lazyCodeLoading": "requiredComponents"} - 每个页面的 json 必须配置
"navigationStyle": "custom"： // ❌ 错误：缺少 navigationStyle，编译报错 // getAppConfig error: the "navigationStyle" configuration // for the page should be set to "custom" {"usingComponents": {}} // ✅ 正确 {"navigationStyle": "custom"} Skyline 不支持原生导航栏，必须使用自定义导航栏。 - 使用 scroll-view 替代页面级滚动时配置
"disableScroll": true： // ❌ 错误：未禁用页面滚动，可能与 scroll-view 冲突 {"navigationStyle": "custom"} // ✅ 正确：禁用页面滚动，使用 scroll-view 管理滚动 {"navigationStyle": "custom", "disableScroll": true} - rendererOptions 应配置 defaultDisplayBlock 和 defaultContentBox 以对齐 WebView 行为：
// ❌ 错误：未配置 rendererOptions，Skyline 默认 display:flex + border-box {"renderer": "skyline"} // ✅ 正确：对齐 WebView 的 block + content-box 默认行为 {"renderer": "skyline", "rendererOptions": {"skyline": {"defaultDisplayBlock": true, "defaultContentBox": true}}}
NEVER（禁止行为）
- NEVER 遗漏任何页面的
navigationStyle: "custom" 配置——即使页面不需要导航栏，Skyline 下也必须声明 - NEVER 在 Skyline 页面中依赖页面级全局滚动——Skyline 不支持页面级滚动，必须使用
scroll-view 组件
Quick Reference
必需配置速查
| 配置项 | 位置 | 值 | 级别 |
|---|
renderer | app.json | "skyline" | 必需 |
componentFramework | app.json | "glass-easel" | 必需 |
lazyCodeLoading | app.json | "requiredComponents" | 必需 |
navigationStyle | 页面 json | "custom" | 必需 |
disableScroll | 页面 json | true | 推荐 |
rendererOptions 配置速查
| 配置项 | 类型 | 默认值 | 推荐值 | 说明 |
|---|
defaultDisplayBlock | boolean | false | true | 默认 display:block（对齐 WebView） |
defaultContentBox | boolean | false | true | 默认 box-sizing:content-box（对齐 WebView） |
tagNameStyleIsolation | string | "isolated" | "legacy" | 标签选择器全局匹配（对齐 WebView） |
enableScrollViewAutoSize | boolean | false | true | scroll-view 自动撑开高度 |
disableABTest | boolean | false | true | 关闭 Skyline AB 实验，确保稳定性 |
场景决策表
| 场景 | 推荐配置 |
|---|
| 新建 Skyline 项目 | 三项必需 + rendererOptions 全部推荐值 |
| WebView 迁移 | 三项必需 + rendererOptions 兼容配置 + disableABTest |
| 混合渲染 | app.json 不设 renderer，页面级单独设 "renderer": "skyline" |
| 仅部分页面用 Skyline | 页面 json 中设 "renderer": "skyline" 覆盖全局 |
相关技能
| 场景 | 推荐技能 | 说明 |
|---|
| WXSS 样式兼容 | skyline-wxss | rendererOptions 影响的默认值详解（display/flex-direction/align-items/box-sizing） |
| glass-easel 框架 | skyline-glass-easel | componentFramework 详细迁移指南 |
| Skyline 概览与迁移 | skyline-overview | 渲染引擎概览、迁移步骤 |
| 组件使用 | skyline-components | scroll-view 等组件配置 |
| 路由配置 | skyline-route | 自定义路由与页面转场 |
References 目录结构
references/
├── app-config.md
├── page-config.md
├── patterns.md
└── project-config.md
