跳轉到

教學 0 - 讓我們開始設定！

在建立第一個 BeeWare 應用程式之前，我們必須確保具備運行 BeeWare 的所有先決條件。

安裝 Python

我們首先需要的是一個可用的 Python 直譯器。

如果您使用的是 Windows，則可以從 Python 網站 取得官方安裝程式。您可以使用 3.8 及以上的任何穩定版本的 Python。我們建議避免 alpha、beta 和候選版本，除非您 真的 知道自己在做什麼。

安裝 Python 有很多不同的方法。您可以透過 homebrew 安裝 Python。您可以使用 pyenv 來管理同一台電腦上的多個 Python 安裝。 Windows 使用者可以從 Windows App Store 安裝 Python。有數據科學背景的用戶可能希望使用 Anaconda 或 Miniconda 。

Xcode 和 Command-line 開發者工具提供了 Python 版本，但該 Python 版本為 3.9。Python 3.9 已經到了生命末期，Python 或 BeeWare 都不再支援。您將**無法使用 Xcode 提供的 Python 版本來執行本教學。

若要檢查已安裝的 Python 版本，請執行下列指令：

$ python3 --version

如果已安裝 Python，您會看到它的版本號。

如果您使用的是 Linux，則會使用系統套件管理器（Debian/Ubuntu/Mint 上的 apt 、Fedora 上的 dnf 或 Arch 上的 pacman ）安裝 Python。

您應該確保系統Python是Python 3.8或更高版本；如果不是（例如，Ubuntu 18.04 附帶 Python 3.6），則需要將 Linux 發行版升級到更新的版本。

目前對 Raspberry Pi 的支援有限。

重要提示：您必須使用作業系統提供的系統版 Python。若使用其他來源安裝的 Python（例如 uv、pyenv、Anaconda 或手動編譯的 Python 等），將導致您無法在本教學後續步驟中成功封裝應用程式以供分發。

如果您使用的是 Windows，則可以從 Python 網站 取得官方安裝程式。您可以使用 3.8 及以上的任何穩定版本的 Python。我們建議避免 alpha、beta 和候選版本，除非您 真的 知道自己在做什麼。

目前對 Raspberry Pi 的支援有限。

如果你在 macOS 或 Windows 上，你如何安裝 Python 並不重要 - 重要的是你可以從作業系統的命令提示字元/終端應用程式運行 python3 ，並獲得一個可用的 Python 直譯器。

安裝依賴項目

接下來，安裝作業系統所需的其他依賴項：

在 macOS 上建立 BeeWare 應用程式需要：

  • Git，一個版本控制系統。它包含在您上面安裝的 Xcode 或命令列開發工具中。您可能需要首次打開 Xcode 才能讓 Git 在您的終端會話中運行。如果還是沒有註冊到 Git 已經安裝，您可能需要重新啟動您的終端會話。

為了支援本地開發，您需要安裝一些系統軟體包。所需的軟體包清單因您的發行版而異：

Ubuntu 20.04+ / Debian 10+

$ sudo apt update
$ sudo apt install git build-essential pkg-config python3-dev python3-venv libgirepository1.0-dev libcairo2-dev gir1.2-gtk-3.0 libcanberra-gtk3-module

紅帽 / Fedora

$ sudo dnf install git gcc make pkg-config rpm-build python3-devel gobject-introspection-devel cairo-gobject-devel gtk3 libcanberra-gtk3

Arch, Manjaro

$ sudo pacman -Syu git base-devel pkgconf python3 gobject-introspection cairo gtk3 libcanberra

OpenSUSE Tumbleweed

$ sudo zypper install git patterns-devel-base-devel_basis pkgconf-pkg-config python3-devel gobject-introspection-devel cairo-devel gtk3 'typelib(Gtk)=3.0' libcanberra-gtk3-module

其他 Linux 發行版

若您使用的 Linux 發行版未列於此清單，且非源自清單中任何發行版（例如：Linux Mint 與 Pop! OS 皆為 Debian 衍生發行版；AlmaLinux 則源自 Fedora），您可能難以完成本教學。若 Briefcase 警告「無法驗證系統套件」，則無法完成本教學。

在 Windows 上建立 BeeWare 應用程式需要：

  • Git ，版本控制系統。您可以從 [git-scm.com] 下載 Git。

安裝這些工具後，您應該確保重新啟動所有終端會話。 Windows 只會公開安裝完成 之後 啟動的新安裝的工具終端。

設定虛擬環境

現在，我們將創建一個虛擬環境 - 一個 [沙箱` ，我們可以使用它來將本教程的工作與主 Python 安裝隔離。如果我們將套件安裝到虛擬環境中，我們的主要 Python 安裝（以及我們電腦上的任何其他 Python 專案）將不會受到影響。如果我們把虛擬環境弄得一團糟，我們只需刪除它並重新開始，就不會影響我們電腦上的任何其他 Python 項目，也不需要重新安裝 Python。

$ mkdir beeware-tutorial
$ cd beeware-tutorial
$ python3 -m venv beeware-venv
$ source beeware-venv/bin/activate

$ mkdir beeware-tutorial
$ cd beeware-tutorial
$ python3 -m venv beeware-venv
$ source beeware-venv/bin/activate

C:\...>md beeware-tutorial
C:\...>cd beeware-tutorial
C:\...>py -3.12 -m venv beeware-venv
C:\...>beeware-venv\Scripts\activate

如果您使用的不是 Python 3.12，請將這些說明中的「-3.12」換成您正在使用的版本號碼。

執行 PowerShell 腳本的錯誤

如果您使用 PowerShell，並且收到錯誤:

File C:\...\beeware-tutorial\beeware-venv\Scripts\activate.ps1 cannot be loaded because running scripts is disabled on this system.

您的 Windows 帳戶沒有執行指令碼的權限。要解決這個問題：

  1. 以管理員身分執行 Windows PowerShell。
  2. 運行 set-executionpolicy RemoteSigned
  3. 選擇 Y 更改執行策略。

完成此操作後，您可以在原始 PowerShell 會話（或同一目錄中的新會話）中重新執行 beeware-venv\Scripts\activate.ps1 。

如果這有效，你的提示現在應該改變 - 它應該有一個 (beeware-venv) 前綴。這可以讓您知道您目前處於 BeeWare 虛擬環境。每當您學習本教學時，您都應該確保您的虛擬環境已啟動。如果不是，請重新執行最後一個命令（ activate 命令）以啟動您的虛擬環境。

替代性虛擬環境

如果您正在使用 Anaconda 或 miniconda，您可能更熟悉使用 conda 環境。您可能也聽過 virtualenv，它是 Python 內建的 venv 模組的前身。就像 Python 安裝一樣 - 如果您在 macOS 或 Windows 上，只要您有一個虛擬環境，以何種方式創建並不重要。如果您在 Linux 上，您應該堅持使用 venv 和系統 Python。

下一步

我們現在已經設定好了我們的環境。我們準備好 [創建我們的第一個 BeeWare 應用程式[。