跳转至

教程 0 - 准备就绪！

在构建第一个使用 BeeWare 的应用程序之前，我们必须确保已具备运行 BeeWare 的所有先决条件。

安装 Python

首先，我们需要一个正常工作的 Python 解释器。

如果您使用 macOS，您可以从 Python 网站_\ 获取官方安装程序。您可以使用 Python 3.10 以上时任何版本，但避免使用 Alpha、Beta 和候选版本。我们强烈建议使用 Python 3.13 或更新版本。

安装 Python 也有很多其他不同的方法。您可以通过 homebrew 安装 Python，或使用 pyenv来管理同一台机器上的多个 Python 安装，或使用 Anaconda 或 Miniconda。怎么\ 安装 Python 并不重要，只要可以从终端运行 python3 并获取到支持的、正常工作的 Python 解释器即可。

Xcode 和命令行开发工具提供了一个 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.9 或更高；如果不是（例如，Ubuntu 20.04 附带 Python 3.8），您需要将您的 Linux 发行版升级到更新版本。

目前对 Raspberry Pi 的支持有限。

重要提示：您必须使用操作系统自带的系统版Python。若使用其他来源安装的Python（如uv、pyenv、Anaconda、手动编译的Python等），将导致后续教程步骤中无法成功打包应用程序进行分发。

如果您使用的是 Windows，您可以从 Python 网站\ 获取官方安装程序。您可以使用 Python 3.9 到 3.13 的任何稳定版本。我们还建议避免使用 Alpha、Beta 和候选版本，除非你\ 真的\ 知道自己在做什么。

目前对 Raspberry Pi 的支持有限。

安装 Python 也有很多其他不同的方法。您可以通过 homebrew 安装 Python，或使用 pyenv来管理同一台机器上的多个 Python 安装，或使用 [Anaconda]{3} 或 [Miniconda]{4}。怎么\ 安装 Python 并不重要，只要可以从终端运行 python3 并获取到支持的、正常工作的 Python 解释器即可。

安装依赖项

接下来，安装您的操作系统所需的其他依赖项：

在 macOS 上构建 BeeWare 应用程序需要：

  • Git，一个版本控制系统。上面已安装的 Xcode 或其命令行开发工具已经包含了Git。您可能需要第一次打开 Xcode 以后才能再命令行会话中使Git正常工作。如果仍然无法识别 Git，可能需要重启您的命令行会话。

为支持本地开发，您将需要安装一些系统软件包。所需的软件包列表因发行版而异：

Ubuntu 或 Debian

$ 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. 以管理员身份运行 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。

下一步

现在我们已经设置好了环境。我们已经准备创建\ 您的第一个应用程序\ 了。