這些環境變數只能處理**文字字串**，因為它們是位於 Python 範疇之外的，必須與其他程式和作業系統的其餘部分相容（甚至與不同的作業系統相容，如 Linux、Windows、macOS）。

這意味著從環境變數中讀取的**任何值**在 Python 中都將是一個 `str`，任何型別轉換或驗證都必須在程式碼中完成。

你將在[進階使用者指南 - 設定和環境變數](./advanced/settings.md)中了解更多關於使用環境變數處理**應用程式設定**的資訊。

## `PATH` 環境變數 { #path-environment-variable }

有一個**特殊的**環境變數稱為 **`PATH`**，作業系統（Linux、macOS、Windows）用它來查找要執行的程式。

`PATH` 變數的值是一個長字串，由 Linux 和 macOS 上的冒號 `:` 分隔的目錄組成，而在 Windows 上則是由分號 `;` 分隔的。

name: publish

on:
  push:
    tags:
      - '**'

env:
  GRADLE_OPTS: "-Dorg.gradle.jvmargs=-Xmx4g -Dorg.gradle.daemon=false -Dkotlin.incremental=false"

jobs:
  publish:
    runs-on: macos-15

    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-java@v5
        with:
          distribution: 'temurin'
          java-version-file: .github/workflows/.java-version

      - run: ./gradlew publish

- **Route Search** - Search by path, method, or name with <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>E</kbd> (on macOS: <kbd>Cmd</kbd> + <kbd>Shift</kbd> + <kbd>E</kbd>).

///

Activating a virtual environment adds its path `.venv/bin` (on Linux and macOS) or `.venv\Scripts` (on Windows) to the `PATH` environment variable.

Let's say that before activating the environment, the `PATH` variable looked like this:

//// tab | Linux, macOS

```plaintext
/usr/bin:/bin:/usr/sbin:/sbin
```

That means that the system would look for programs in:

      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        java: ['17', '21', '25']
    steps:
      - name: Set up JDK ${{ matrix.java }}
        uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5.2.0
        with:
          java-version: ${{ matrix.java }}
          distribution: 'temurin'

      - name: Install Graphviz (MacOS)
        if: runner.os == 'macOS'

## 功能 { #features }

- **Path Operation 资源管理器** - 侧边栏树状视图展示应用中的所有 <dfn title="路由，端点">*路径操作*</dfn>。点击可跳转至任一路由或 APIRouter 的定义。
- **路由搜索** - 使用 <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>E</kbd>（macOS 上为 <kbd>Cmd</kbd> + <kbd>Shift</kbd> + <kbd>E</kbd>）按路径、方法或名称进行搜索。
- **CodeLens 导航** - 测试客户端调用（例如 `client.get('/items')`）上方的可点击链接，可跳转到匹配的*路径操作*，在测试与实现之间快速往返。
- **部署到 FastAPI Cloud** - 一键将你的应用部署到 [FastAPI Cloud](https://fastapicloud.com/)。

## 功能 { #features }

- **Path Operation Explorer** - 顯示應用程式中所有 <dfn title="路由、端點">*路徑操作*</dfn> 的側邊欄樹狀檢視。點擊即可跳至任一路由或 router 定義。
- **Route Search** - 使用 <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>E</kbd>（macOS：<kbd>Cmd</kbd> + <kbd>Shift</kbd> + <kbd>E</kbd>）依路徑、方法或名稱進行搜尋。
- **CodeLens Navigation** - 在測試用 client 呼叫（例如 `client.get('/items')`）上方提供可點連結，一鍵跳至對應的路徑操作，讓你在測試與實作間快速切換。

/// tip | 提示

你可以在 [环境变量](environment-variables.md#path-environment-variable) 部分了解更多关于 `PATH` 环境变量的内容。

///

激活虚拟环境会将其路径 `.venv/bin`（在 Linux 和 macOS 上）或 `.venv\Scripts`（在 Windows 上）添加到 `PATH` 环境变量中。

假设在激活环境之前，`PATH` 变量看起来像这样：

//// tab | Linux, macOS

```plaintext
/usr/bin:/bin:/usr/sbin:/sbin
```

这意味着系统会在以下目录中查找程序：

* `/usr/bin`
* `/bin`
* `/usr/sbin`
* `/sbin`

## Ports {#ports}

### Darwin {#darwin}

<!-- go.dev/issue/75836 -->
As [announced](go1.26#darwin) in the Go 1.26 release notes,
Go 1.27 requires macOS 13 Ventura or later;

site
.coverage*
coverage.xml
.netlify
test.db
log.txt
Pipfile.lock
env3.*
env
docs_build
site_build
venv
docs.zip
archive.zip

# vim temporary files
*~
.*.sw?
.cache

# macOS
.DS_Store