Skyline JSON 配置规范

适用场景

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

核心概念

三级配置层次

app.json

页面.json

project.config.json

最小必需配置

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

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

文档索引

references/

app-config.md

page-config.md

project-config.md

patterns.md

强制规则

MUST（必须遵守）

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

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

2. 每个页面的 json 必须配置

   "navigationStyle": "custom"

   ：
   json

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

   Skyline 不支持原生导航栏，必须使用自定义导航栏。
3. 使用 scroll-view 替代页面级滚动时配置

   "disableScroll": true

   ：
   json

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

4. rendererOptions 应配置 defaultDisplayBlock 和 defaultContentBox 以对齐 WebView 行为：
   json

   // ❌ 错误：未配置 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

必需配置速查

renderer

"skyline"

componentFramework

"glass-easel"

lazyCodeLoading

"requiredComponents"

navigationStyle

"custom"

disableScroll

true

rendererOptions 配置速查

defaultDisplayBlock

defaultContentBox

tagNameStyleIsolation

enableScrollViewAutoSize

disableABTest

场景决策表

"renderer": "skyline"

"renderer": "skyline"

相关技能

skyline-wxss

skyline-glass-easel

skyline-overview

skyline-components

skyline-route

References 目录结构

references/
├── app-config.md
├── page-config.md
├── patterns.md
└── project-config.md