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
├── page-config.md
├── patterns.md
└── project-config.md

app.json Skyline 配置详解

概述

小程序全局配置文件 app.json 中，以下配置项与 Skyline 渲染引擎直接相关。本文档仅列出 Skyline 相关配置，完整 app.json 配置请参阅官方文档。

renderer

基础库 2.30.4+

指定小程序全局的默认渲染后端。

{
  "renderer": "skyline"
}

componentFramework

基础库 2.30.4+

指定小程序使用的组件框架。Skyline 项目必须配置为 glass-easel。

{
  "componentFramework": "glass-easel"
}

📌 glass-easel 迁移详情请参阅：skyline-glass-easel

lazyCodeLoading

基础库 2.11.1+

配置自定义组件代码按需注入。目前仅支持值 requiredComponents。

{
  "lazyCodeLoading": "requiredComponents"
}

开启后，小程序仅在页面实际使用到某组件时才注入该组件代码，显著优化启动性能。

rendererOptions

基础库 2.31.1+

Skyline 渲染引擎的配置选项，嵌套在 rendererOptions.skyline 下。

完整配置项

defaultDisplayBlock 效果对比

/* 默认值 false：Skyline 默认 flex 布局 */
view {
  display: flex;
  flex-direction: column;
  align-items: stretch;
}

/* 设为 true：对齐 WebView 行为 */
view {
  display: block;
  flex-direction: row;    /* 虽然 display:block 时不生效，但默认值变化 */
  align-items: normal;    /* 虽然 display:block 时不生效，但默认值变化 */
}

⚠️ 迁移项目强烈建议开启此选项，否则大量使用 display: block 假设的样式将失效。

defaultContentBox 效果对比

/* 默认值 false：Skyline 默认 border-box */
view { box-sizing: border-box; }

/* 设为 true：对齐 WebView 行为 */
view { box-sizing: content-box; }

tagNameStyleIsolation 说明

disableABTest 说明

Skyline 通过 AB 实验逐步扩大用户覆盖范围。开启 disableABTest: true 后：

• 所有用户均使用 Skyline 渲染
• 不再参与灰度实验
• 发布上线时建议开启，确保行为一致性

{
  "rendererOptions": {
    "skyline": {
      "disableABTest": true,
      "defaultDisplayBlock": true,
      "defaultContentBox": true,
      "tagNameStyleIsolation": "legacy",
      "enableScrollViewAutoSize": true
    }
  }
}

window.navigationStyle

app.json 的 window 字段中，navigationStyle 控制导航栏样式。Skyline 下必须设为 "custom"。

{
  "window": {
    "navigationStyle": "custom"
  }
}

在 window 中设置的 navigationStyle 作为全局默认值，仍需在每个页面 json 中显式声明（确保明确性）。

convertRpxToVw

基础库 3.3.0+

配置是否将 rpx 单位转换为 vw 单位，开启后能修复某些 rpx 下的精度问题。

{
  "convertRpxToVw": true
}

页面级配置详解

概述

每个页面的 .json 文件可以对当前页面进行独立配置，覆盖 app.json 中的全局设置。本文档聚焦于 Skyline 相关的页面级配置项。

navigationStyle（必需）

Skyline 下必须设为 `"custom"`。Skyline 不支持原生导航栏渲染，未配置将导致编译错误：

getAppConfig error: the "navigationStyle" configuration for the page should be set to "custom"

{
  "navigationStyle": "custom"
}

⚠️ 即使在 app.json 的 window 中已设置 "navigationStyle": "custom"，每个页面 json 仍建议显式声明，确保配置明确。

自定义导航栏实现

配置 "navigationStyle": "custom" 后，页面顶部没有默认导航栏，需要自行实现：

<!-- 自定义导航栏组件 -->
<view class="nav-bar" style="padding-top: {{statusBarHeight}}px;">
  <view class="nav-bar__title">页面标题</view>
</view>
<scroll-view type="list" scroll-y style="height: 100vh;">
  <!-- 页面内容 -->
</scroll-view>

disableScroll

注意：此配置只在页面 json 中有效，无法在 app.json 中设置。

Skyline 不支持页面级全局滚动，建议配置 "disableScroll": true 并使用 scroll-view 组件管理滚动：

{
  "navigationStyle": "custom",
  "disableScroll": true
}

backgroundColorContent

Skyline 特有属性

用于设置页面容器的背景色，支持带透明度的颜色值。常用于自定义路由中设置页面透明背景：

{
  "navigationStyle": "custom",
  "backgroundColorContent": "#00000000"
}

📌 透明页面背景详情请参阅：skyline-route - 自定义路由

renderer（页面级覆盖）

基础库 2.30.4+

页面级的 renderer 配置可覆盖 app.json 中的全局设置，实现混合渲染：

// 某个页面使用 Skyline（即使全局是 WebView）
{
  "renderer": "skyline",
  "navigationStyle": "custom",
  "componentFramework": "glass-easel"
}

// 某个页面回退到 WebView（即使全局是 Skyline）
{
  "renderer": "webview"
}

混合渲染策略

rendererOptions（页面级覆盖）

基础库 3.1.0+

页面级可以覆盖 app.json 中的 rendererOptions 配置：

{
  "navigationStyle": "custom",
  "rendererOptions": {
    "skyline": {
      "defaultDisplayBlock": false
    }
  }
}

componentFramework（页面级覆盖）

基础库 2.30.4+

页面级可以覆盖组件框架配置。混合渲染中使用 Skyline 的页面必须同时配置：

{
  "renderer": "skyline",
  "componentFramework": "glass-easel",
  "navigationStyle": "custom"
}

标准页面 json 模板

基础页面

{
  "navigationStyle": "custom",
  "usingComponents": {
    "nav-bar": "/components/nav-bar/index"
  }
}

可滚动页面

{
  "navigationStyle": "custom",
  "disableScroll": true,
  "usingComponents": {
    "nav-bar": "/components/nav-bar/index"
  }
}

透明背景页面（用于自定义路由）

{
  "navigationStyle": "custom",
  "backgroundColorContent": "#00000000",
  "disableScroll": true
}

配置模板

模板 1：新项目 app.json

适用于从零创建的 Skyline 项目，包含所有推荐配置。

{
  "pages": [
    "pages/index/index",
    "pages/detail/detail"
  ],
  "window": {
    "navigationStyle": "custom",
    "navigationBarTextStyle": "black",
    "backgroundColor": "#f5f5f5"
  },
  "renderer": "skyline",
  "componentFramework": "glass-easel",
  "lazyCodeLoading": "requiredComponents",
  "rendererOptions": {
    "skyline": {
      "defaultDisplayBlock": true,
      "defaultContentBox": true,
      "tagNameStyleIsolation": "legacy",
      "enableScrollViewAutoSize": true,
      "disableABTest": true
    }
  }
}

模板 2：迁移项目 app.json

适用于从 WebView 迁移到 Skyline 的项目，包含所有兼容配置。

{
  "pages": [
    "pages/index/index",
    "pages/list/list",
    "pages/detail/detail"
  ],
  "window": {
    "navigationStyle": "custom",
    "navigationBarBackgroundColor": "#ffffff",
    "navigationBarTextStyle": "black",
    "backgroundColor": "#f5f5f5"
  },
  "renderer": "skyline",
  "componentFramework": "glass-easel",
  "lazyCodeLoading": "requiredComponents",
  "rendererOptions": {
    "skyline": {
      "defaultDisplayBlock": true,
      "defaultContentBox": true,
      "tagNameStyleIsolation": "legacy",
      "enableScrollViewAutoSize": true,
      "disableABTest": true
    }
  },
  "sitemapLocation": "sitemap.json"
}

迁移要点

• defaultDisplayBlock: true — 对齐 WebView 的 display: block 默认行为
• defaultContentBox: true — 对齐 WebView 的 box-sizing: content-box 默认行为
• tagNameStyleIsolation: "legacy" — 标签选择器全局匹配，对齐 WebView
• disableABTest: true — 关闭灰度实验，确保所有用户体验一致

模板 3：混合渲染 app.json

适用于渐进式迁移，全局 WebView + 部分页面 Skyline。

{
  "pages": [
    "pages/index/index",
    "pages/skyline-page/skyline-page",
    "pages/webview-page/webview-page"
  ],
  "window": {
    "navigationBarTextStyle": "black",
    "backgroundColor": "#f5f5f5"
  },
  "lazyCodeLoading": "requiredComponents",
  "sitemapLocation": "sitemap.json"
}

对应的 Skyline 页面 json：

// pages/skyline-page/skyline-page.json
{
  "renderer": "skyline",
  "componentFramework": "glass-easel",
  "navigationStyle": "custom",
  "disableScroll": true,
  "rendererOptions": {
    "skyline": {
      "defaultDisplayBlock": true,
      "defaultContentBox": true
    }
  }
}

对应的 WebView 页面 json（无需特殊配置）：

// pages/webview-page/webview-page.json
{
  "navigationBarTitleText": "WebView 页面"
}

模板 4：标准页面 json

基础页面

{
  "navigationStyle": "custom",
  "usingComponents": {
    "nav-bar": "/components/nav-bar/index"
  }
}

可滚动页面

{
  "navigationStyle": "custom",
  "disableScroll": true,
  "usingComponents": {
    "nav-bar": "/components/nav-bar/index"
  }
}

透明背景页面（自定义路由）

{
  "navigationStyle": "custom",
  "backgroundColorContent": "#00000000",
  "disableScroll": true
}

配置检查清单

新项目检查清单

迁移项目额外检查

project.config.json 配置

概述

project.config.json 是微信开发者工具的项目配置文件，其中包含影响 Skyline 调试和开发的设置项。

配置文件优先级

project.private.config.json 中的相同设置优先级高于 project.config.json。

Skyline 相关设置

setting.skylineRenderEnable

在开发者工具中启用 Skyline 渲染调试：

{
  "setting": {
    "skylineRenderEnable": true
  }
}

⚠️ 此设置仅影响开发者工具的调试行为，不影响线上表现。线上渲染器由 app.json 的 renderer 字段决定。

其他相关设置

以下设置虽非 Skyline 专属，但在 Skyline 项目中常用：

完整示例

{
  "appid": "wx1234567890",
  "compileType": "miniprogram",
  "setting": {
    "skylineRenderEnable": true,
    "es6": true,
    "postcss": true,
    "minified": true,
    "compileHotReLoad": true
  },
  "libVersion": "3.3.0"
}

libVersion

基础库版本设置。Skyline 项目建议设置为 2.30.4 以上版本：