> ## Documentation Index
> Fetch the complete documentation index at: https://ppio.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 连接 Volume

`ppio.volume.connect()` 按 ID 连接到已有 Volume，并返回一个可挂载到 Sandbox 的 `Volume` 实例。可用它复用之前（在其他进程、会话或服务中）创建的 Volume，而无需重新创建。

## 连接 Volume

传入已有 Volume 的 ID。返回的实例携带 Volume ID 和名称。

<CodeGroup>
  ```python Python theme={null}
  from ppio_sandbox import PPIO

  ppio = PPIO()

  volume = ppio.volume.connect("vol-123")

  print("Volume ID:", volume.volume_id)
  print("Name:", volume.name)
  ```

  ```typescript JavaScript & TypeScript theme={null}
  import { PPIO } from 'ppio-sandbox'

  const ppio = new PPIO()

  const volume = await ppio.volume.connect('vol-123')

  console.log('Volume ID:', volume.volumeId)
  console.log('Name:', volume.name)
  ```

  ```bash CLI theme={null}
  # CLI 无独立的 connect 命令；使用 volume get 按 ID 或名称查询已有 Volume
  ppio volume get <volume_id>
  ```
</CodeGroup>

## 先连接，再挂载到 Sandbox

常见流程是：连接到已有 Volume，创建 Sandbox，挂载该 Volume，读取之前持久化的数据，然后清理。先前 Sandbox 写入的数据依然存在。

<CodeGroup>
  ```python Python theme={null}
  from ppio_sandbox import PPIO

  ppio = PPIO()

  # 1. 按 ID 连接到一个已有的 Volume。
  volume = ppio.volume.connect("vol-123")

  # 2. 创建一个 Sandbox。
  sandbox = ppio.sandbox.create()

  try:
      # 3. 将 Volume 挂载到沙箱内的某个路径。
      sandbox.mount_volume(volume.name, "/mnt/data")

      # 4. 读取之前持久化到 Volume 中的数据。
      result = sandbox.commands.run("cat /mnt/data/note.txt")
      print(result.stdout)
  finally:
      # 5. 清理 Sandbox。Volume 及其中的数据仍然保留。
      sandbox.kill()
  ```

  ```typescript JavaScript & TypeScript theme={null}
  import { PPIO } from 'ppio-sandbox'

  const ppio = new PPIO()

  // 1. 按 ID 连接到一个已有的 Volume。
  const volume = await ppio.volume.connect('vol-123')

  // 2. 创建一个 Sandbox。
  const sandbox = await ppio.sandbox.create()

  try {
      // 3. 将 Volume 挂载到沙箱内的某个路径。
      await sandbox.mountVolume(volume.name, '/mnt/data')

      // 4. 读取之前持久化到 Volume 中的数据。
      const result = await sandbox.commands.run('cat /mnt/data/note.txt')
      console.log(result.stdout)
  } finally {
      // 5. 清理 Sandbox。Volume 及其中的数据仍然保留。
      await sandbox.kill()
  }
  ```
</CodeGroup>

<Note>
  `ppio.volume.connect()` 只查找已有 Volume，不会创建新的。如果 Volume ID 不存在，调用会抛出 not-found 错误（`404`）。要创建新的 Volume，请使用 `ppio.volume.create()`。
</Note>