---
url: /zh/workspaces/only-preview.md
description: |
  介绍云原生开发的仅预览模式（beta）， 该模式下点击云原生开发按钮将直接启动并打开预览页面而非 WebIDE， 适用于快速预览业务效果的场景。
---
仅预览模式是云原生开发的衍生能力。在该模式下，点击 `云原生开发` 按钮
将直接打开预览页面而非 WebIDE，预览更快捷。

:::tip 注意事项

1. 此功能为 beta 版本，相关配置和使用方法后续可能会变更。
2. 仅预览模式不支持 WebIDE，可借助[自定义按钮](../build/web-trigger.md)创建支持 WebIDE 的云开发按钮入口。
3. 若要使用 SSH 连接，请自行在镜像中安装 openssh。
4. 仅预览模式不支持代理，`$CNB_VSCODE_PROXY_URI` 环境变量在此模式下无效。如需代理，请使用标准云开发模式。
   :::

## 如何配置？

**最简配置**：

```yaml title=".cnb.yml"
$:
  vscode:
    - docker:
        build: .ide/Dockerfile
      services:
        - name: vscode
          options:
            onlyPreview: true
            launch: node index.js
```

**完整配置示例**（含所有可选参数）：

```yaml title=".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` 脚本启动业务并确认端口就绪后，应当**自行退出**，
  建议在脚本内将业务转到后台运行后再退出；
* 若 `launch` 长时间不退出（例如业务以前台阻塞方式运行，
  超过 5 分钟仍未退出），本次执行会因超时而失败。

**`daemon: true`（守护进程模式）**

平台以\*\*后台（detach）\*\*方式执行 `launch` 命令：

* `launch` 启动的服务直接运行在后台，`docker exec` 立即返回，
  无需等待 `launch` 退出；
* 因为是后台方式执行，**无法查看 `launch` 的启动日志**。

::: tip 推荐做法
默认保持 `daemon: false`，在 `launch` 脚本中自行实现：启动业务并确认端口
就绪后，将业务转入后台并让脚本退出。这样既能查看启动日志定位问题，
又不会因脚本不退出而阻塞流程。
:::

无论采用哪种模式，`launch` 执行完成后，平台都会定时（每 10 秒、
最多约 200 秒）检测容器内 `8686` 端口是否已被监听，确认业务服务已就绪后
才打开预览页面。请确保 `launch` 最终能把业务服务启动在 `8686` 端口上。

### backup

* 类型：`Boolean`
* 默认值：`false`
* 说明：是否备份/恢复用户数据（仅在预览模式下生效）。设置为 `true` 时：
  * 启动时：恢复上次的用户漫游数据和未提交的代码更改
  * 运行时：定时备份未提交的代码更改
  * 关闭时：备份用户漫游数据和未提交的代码更改

## 使用流程

1. 在项目根目录创建 `.cnb.yml` 文件
2. 按上述配置示例配置
3. 确保业务服务监听在 `8686` 端口
4. 点击云原生开发按钮
5. 系统将自动启动开发环境并打开预览页面

## 仅预览模式如何使用 SSH 连接？

需在自定义开发环境中安装 openssh，在 `.ide/Dockerfile` 中配置示例如下：

```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
```

仅预览模式环境创建后直接进入预览页面，不展示客户端选择页。如需客户端连接，可在「头像 → 我的云原生开发」页面找到入口。