1282 字约 4 分钟
仅预览模式 说明如何让「云原生开发」按钮直接打开业务预览页。
使用场景：只想快速查看业务跑起来的效果、不需要在浏览器里编辑代码时使用—— 点击按钮后跳过 WebIDE，直接进入预览页面。
仅预览模式是云原生开发的衍生能力：点击 云原生开发 按钮直接打开预览页面而非 WebIDE， 预览更快捷。
注意事项
- 此功能为 beta 版本，配置和使用方法后续可能变更。
- 仅预览模式不支持 WebIDE；如需 WebIDE，可用自定义按钮另建入口。
- 若要使用 SSH 连接，请自行在镜像中安装 openssh。
- 仅预览模式不支持代理，
$CNB_VSCODE_PROXY_URI在此模式下无效；如需代理，请改用标准云开发模式。
如何配置？
最简配置：
.cnb.yml
$:
vscode:
- docker:
build: .ide/Dockerfile
services:
- name: vscode
options:
onlyPreview: true
launch: node index.js完整配置示例（含全部可选参数）：
.cnb.yml
$:
vscode:
- docker:
build: .ide/Dockerfile
services:
- docker # 可选：额外挂载 docker 服务
- name: vscode
options:
onlyPreview: true # 必填：启用仅预览模式
launch: node index.js # 必填：启动业务服务的命令
keepAliveTimeout: 10m # 可选：离线保活时间，默认 10 分钟
daemon: true # 可选：守护进程模式
backup: true # 可选：备份/恢复用户数据
stages:
- name: prepare # 可选：自定义启动前准备步骤
script: ls -al各参数详细说明见下方参数详解。
参数详解
onlyPreview
- 类型：
Boolean - 说明：是否启用仅预览模式
- 效果：设置为
true时，点击云原生开发按钮打开预览页面而非 WebIDE。若需 SSH，请自行在镜像中安装 openssh
launch
- 类型：
String - 说明：启动业务服务的命令
- 注意：业务服务必须启动在
8686端口 - 示例：
node index.js、npm start、python app.py等
keepAliveTimeout
- 类型：
Number|String（单位默认为毫秒） - 默认值：
600000（10 分钟） - 说明：开发环境的离线保活时间。超过设定时间检测不到 HTTP 连接时，自动关闭开发环境
- 示例：
7200000表示 2 小时
支持直接写数字（毫秒），或带单位的字符串格式，如 10m 表示 10 分钟。支持以下单位：
ms：毫秒（默认）s：秒m：分钟h：小时
daemon
- 类型：
Boolean - 默认值：
false - 说明：
launch命令的执行模式（守护进程模式）
daemon: false（非守护进程模式，默认）
平台在预览环境内以前台方式执行 launch 命令：
- 启动日志实时可见，便于定位问题；
- 平台要等
launch主动退出后，才继续检测业务是否就绪； - 因此
launch脚本启动业务并确认端口就绪后，应自行退出， 建议先把业务转入后台再退出； - 若
launch长时间不退出（例如业务以前台阻塞方式运行、超过 5 分钟仍未退出）， 本次执行会因超时失败。
daemon: true（守护进程模式）
平台以后台（detach）方式执行 launch 命令：
launch启动的服务直接运行在后台，docker exec立即返回，无需等待其退出；- 因为是后台执行，看不到
launch的启动日志。
推荐做法
默认保持 daemon: false，在 launch 脚本中自行实现：启动业务并确认端口 就绪后，将业务转入后台并让脚本退出。这样既能查看启动日志定位问题， 又不会因脚本不退出而阻塞流程。
两种模式执行完后，平台都会定时检测容器内 8686 端口是否已被监听 （每 10 秒一次，最多约 200 秒），确认业务已就绪后才打开预览页面。 因此请确保 launch 最终把业务启动在 8686 端口上。
backup
- 类型：
Boolean - 默认值：
false - 说明：是否备份/恢复用户数据（仅在预览模式下生效）。设置为
true时：- 启动时：恢复上次的用户漫游数据和未提交的代码更改
- 运行时：定时备份未提交的代码更改
- 关闭时：备份用户漫游数据和未提交的代码更改
使用流程
- 在项目根目录创建
.cnb.yml。 - 按上述示例完成配置。
- 确保业务服务监听在
8686端口。 - 点击云原生开发按钮。
- 系统自动启动开发环境并打开预览页面。
仅预览模式如何使用 SSH 连接？
需在自定义开发环境中安装 openssh，在 .ide/Dockerfile 中配置示例如下：
FROM node:20
RUN apt-get update && apt-get install -y git wget unzip openssh-server
ENV LANG C.UTF-8
ENV LANGUAGE C.UTF-8仅预览模式环境创建后直接进入预览页面，不展示客户端选择页。如需客户端连接，可在「头像 → 我的云原生开发」页面找到入口。