Skyline Config

Skyline JSON 配置规范

适用场景

• 创建新的 Skyline 小程序项目
• 从 WebView 迁移到 Skyline 渲染引擎
• 配置混合渲染（部分页面 Skyline、部分 WebView）
• 配置 rendererOptions 优化样式兼容性
• 排查 Skyline 配置相关的编译错误

核心概念

三级配置层次

最小必需配置

// app.json
{
  "renderer": "skyline",
  "componentFramework": "glass-easel",
  "lazyCodeLoading": "requiredComponents"
}

// 每个页面的 .json
{
  "navigationStyle": "custom"
}

文档索引

根据需求快速定位（路径相对于 references/）：

强制规则

MUST（必须遵守）

1. app.json 必须包含三项必需配置：

   // ❌ 错误：缺少 componentFramework 和 lazyCodeLoading
   {
     "pages": ["pages/index/index"],
     "renderer": "skyline"
   }
   
   // ✅ 正确：三项缺一不可
   {
     "renderer": "skyline",
     "componentFramework": "glass-easel",
     "lazyCodeLoading": "requiredComponents"
   }
   

2. 每个页面的 json 必须配置 "navigationStyle": "custom"：

   // ❌ 错误：缺少 navigationStyle，编译报错
   // getAppConfig error: the "navigationStyle" configuration
   // for the page should be set to "custom"
   {
     "usingComponents": {}
   }
   
   // ✅ 正确
   {
     "navigationStyle": "custom"
   }
   

   Skyline 不支持原生导航栏，必须使用自定义导航栏。

3. 使用 scroll-view 替代页面级滚动时配置 "disableScroll": true：

   // ❌ 错误：未禁用页面滚动，可能与 scroll-view 冲突
   {
     "navigationStyle": "custom"
   }
   
   // ✅ 正确：禁用页面滚动，使用 scroll-view 管理滚动
   {
     "navigationStyle": "custom",
     "disableScroll": true
   }
   

4. 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（禁止行为）

1. NEVER 遗漏任何页面的 navigationStyle: "custom" 配置——即使页面不需要导航栏，Skyline 下也必须声明
2. NEVER 在 Skyline 页面中依赖页面级全局滚动——Skyline 不支持页面级滚动，必须使用 scroll-view 组件

Quick Reference

必需配置速查

rendererOptions 配置速查

场景决策表

相关技能

References 目录结构

references/
├── app-config.md       # app.json Skyline 配置详解（renderer/rendererOptions/componentFramework）
├── page-config.md      # 页面级配置详解（navigationStyle/disableScroll/混合渲染）
├── project-config.md   # project.config.json 配置
└── patterns.md         # 配置模板（新项目/迁移/混合渲染）