---
url: /zh/workspaces/only-preview.md
---
云开发仅预览模式是云原生开发的衍生能力。在该模式下，点击 `云原生开发` 按钮将不会打开 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:
        # launch 启动命令中如需使用到 docker 命令或 docker compose 命令，docker service 需写在 vscode service 前面
        - docker
        - name: vscode
          options:
            # 启用预览模式
            onlyPreview: true
            # 启动业务端口的命令，端口必须启动在 8686
            launch: node index.js
            # 离线保活时间，单位毫秒，不设置默认 10 分钟没有心跳（检测不到开发环境内的 http 连接）即关闭开发环境
            keepAliveTimeout: 10m
            # 是否守护进程模式，默认为 false，非守护进程模式
            # true：以守护进程模式启动，即 launch 启动预览业务服务时，会直接运行在后台
            # false：非守护进程模式启动，执行 launch 启动预览业务服务时，可以看到日志，且需要等待 launch 启动完成并主动退出，才会继续执行后续流程
            # 推荐设置为 false，由用户自己实现业务启动成功后退出进程并后台运行，这样可以看到业务启动日志，方便定位问题
            daemon: true
            # 是否备份/恢复用户数据（该参数仅在预览模式下生效），默认为 false，表示不备份和恢复用户数据
            # 设置为 true 时：启动时恢复上次的用户漫游数据和未提交更改，运行时定时备份，关闭时备份用户漫游数据和未提交更改
            backup: true

      # 开发环境启动后会执行的任务
      stages:
        - name: ls
          script: ls -al
```

## 参数详解

### onlyPreview

* 类型: `Boolean`
* 说明: 是否启用仅预览模式
* 效果: 设置为 `true` 时，点击云原生开发按钮将打开预览页面，而不是 WebIDE。不支持启动 WebIDE，若要使用 SSH 连接，需自行在镜像中安装 openssh

### launch

* 类型: `String`
* 说明: 启动业务服务的命令
* 注意: 业务服务必须启动在 `8686` 端口
* 示例: `node index.js`, `npm start`, `python app.py` 等

### keepAliveTimeout

* 类型: `Number` | `String`（单位默认为：毫秒）
* 默认值: `600000`（ms, 10分钟）
* 说明: 开发环境的离线保活时间。当检测不到开发环境内的 HTTP 连接时，超过设定时间后将自动关闭开发环境
* 示例: `3600000` 表示 1 小时

可直接写数字，表示多少毫秒，也可以写成带单位的字符串格式，例如：`10m` 表示 10 分钟，支持以下单位：

* `ms`: 毫秒(默认)
* `s` : 秒
* `m` : 分钟
* `h` : 小时

### daemon

* 类型: `Boolean`
* 默认值: `false`
* 说明: 进程启动模式配置：
  * `true`（守护进程模式）：launch 命令启动的服务直接运行在后台
  * `false`（非守护进程模式）：可以查看 launch 命令的启动日志，需要等待服务启动完成并主动退出后才会继续后续流程

### backup

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

## 使用流程

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

## 仅预览模式如何支持 SSH 连接？

需要在自定义的开发环境中安装 openssh，示例如下：

自定义开发环境 Dockerfile：

```Dockerfile
# .ide/Dockerfile

# 可将 node 替换为需要的基础镜像
FROM node:20

# 安装 ssh 服务，用于支持 VSCode 等客户端通过 Remote-SSH 访问开发环境（也可按需安装其他软件）
RUN apt-get update && apt-get install -y git wget unzip openssh-server

# 指定字符集支持命令行输入中文（根据需要选择字符集）
ENV LANG C.UTF-8
ENV LANGUAGE C.UTF-8
```