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 必须包含三项必需配置：

```json // ❌ 错误：缺少 componentFramework 和 lazyCodeLoading { "pages": ["pages/index/index"], "renderer": "skyline" }

// ✅ 正确：三项缺一不可 { "renderer": "skyline", "componentFramework": "glass-easel", "lazyCodeLoading": "requiredComponents" } ```

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

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

// ✅ 正确 { "navigationStyle": "custom" } ```

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

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

```json // ❌ 错误：未禁用页面滚动，可能与 scroll-view 冲突 { "navigationStyle": "custom" }

// ✅ 正确：禁用页面滚动，使用 scroll-view 管理滚动 { "navigationStyle": "custom", "disableScroll": true } ```

1. 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

必需配置速查

rendererOptions 配置速查

场景决策表

相关技能

References 目录结构

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