Node、bun 和 PHP 版本

运行时 标签页（R）显示开发服务器和你的终端在项目文件夹中使用的版本，并允许你固定它们。

Node 和包管理器

Joppa 借助 Vite+：它会下载每个项目固定的 Node 版本和包管理器（bun、pnpm、npm、yarn）。无需手动安装：Joppa 在首次启动时安装 Vite+，并附带 Node LTS 和 bun，之后每天更新。电脑上已有的 Vite+ 也会被沿用并以同样方式更新。安装期间，该标签页和 新建项目 窗口会显示进度；如果失败（离线），点击 重试 即可重新安装。

• Node 版本：保持不变、最新 LTS 或某个具体版本。
• 包管理器 及其版本。
• 固定 会写入 .node-version 和 package.json 的 packageManager 字段：之后所有终端和开发服务器都会使用这些版本（vp env pin）。

Joppa 按以下顺序读取版本：devEngines，然后是版本文件（.node-version、.nvmrc），最后是 engines。

终端中的 Node

Joppa 安装 Vite+ 时不会改动你的 shell 配置文件。若要让终端使用固定版本的 node、bun、pnpm、npm 和 yarn，设置 › Node › 在我的终端中使用 Joppa 的 Node 会在你确认后添加以下区块：

# >>> Joppa (Node) >>>
. "/Users/you/.config/vite-plus/env"
# <<< Joppa (Node) <<<

修改的文件取决于你的 shell，与 PHP 相同。如果你的配置文件已加载 Vite+（用其自带命令安装），开关会显示为开启，Joppa 不会再添加任何内容。更改后请打开新终端。

PHP

Joppa 会下载 PHP 的静态构建（static-php.dev），版本从 8.1 到 8.5，并存放在自己的文件夹中。

• 固定一个版本…：选择版本；安装并使用 会在需要时下载它，并在项目根目录写入 .php-version。
• 取消固定 会删除 .php-version。

扩展

扩展 列表显示固定的构建中包含的内容（php -m）：bcmath、curl、gd、mbstring、pdo_mysql、pdo_pgsql、pdo_sqlite、pgsql、redis、soap、zip…… 它们已编译进静态可执行文件：无需安装或启用，列表中没有的扩展（intl、opcache）也无法添加。

项目的 php.ini

项目的 php.ini 会把项目的 PHP 设置写入其根目录下的 .php.ini 文件，每行一个 设置 = 值：

memory_limit = 512M
upload_max_filesize = 64M
post_max_size = 64M

+ memory_limit、+ upload_max_filesize…… 按钮会添加最常用的设置。保存 会用 PHP 检查该文件，然后重启项目正在运行的 PHP 进程。清空内容会删除该文件。

Joppa 的 php 命令会读取最近的 .php.ini（此文件夹或上级文件夹），并通过 PHPRC 变量传给 PHP：你的终端、Composer、php artisan serve 和 worker 都会读取它。没有 .php.ini 时，PHP 使用其默认值（memory_limit = 128M……）。系统 PHP 不受影响：它保留自己的 php.ini。提交 .php.ini 即可与团队共享。

Xdebug

static-php.dev 的静态构建不含 Xdebug。Joppa 提供自己的 Xdebug，为每个 PHP 版本（8.1 到 8.5）编译，在你第一次需要时从 download.getjoppa.com 下载并验证校验和：安装 Xdebug。

设置	作用
为项目进程启用 Xdebug	用 XDEBUG_MODE 和 XDEBUG_CONFIG 重启项目的 PHP 进程
模式	debug（单步调试）、coverage（测试覆盖率）、profile（/tmp 中的 cachegrind 文件），可选一个或多个
触发	按需：仅在有 XDEBUG_TRIGGER 时（浏览器的 Xdebug Helper 扩展、?XDEBUG_TRIGGER=1、cookie）；始终：每个请求和每条命令
IDE 端口	默认为 9003，即 Xdebug 3 的端口

只有设置了 XDEBUG_MODE 才会加载 Xdebug：关闭时不会拖慢任何东西。每次更改都会重启正在运行的 PHP 进程。项目的 worktree 会沿用它的设置。

在终端中，Joppa 的 php 命令以同样的方式加载 Xdebug：

XDEBUG_MODE=coverage php artisan test --coverage
XDEBUG_MODE=debug XDEBUG_TRIGGER=1 php artisan app:import

PhpStorm 和 VS Code

一切都在你的机器上、在项目文件夹中运行：无需设置 path mappings。

• PhpStorm：Settings › PHP › Debug，端口 9003，然后点击 Start Listening for PHP Debug Connections（电话图标）。第一次连接时，接受建议的服务器（shop.test）。
• VS Code：安装 PHP Debug 扩展（xdebug.php-debug），并使用此 launch.json：

{
  "version": "0.2.0",
  "configurations": [{ "name": "Joppa", "type": "php", "request": "launch", "port": 9003 }]
}

终端中的 PHP

Joppa 在其 bin 文件夹中放置了 php 和 composer 命令，它们会读取当前文件夹（或上级文件夹）的 .php-version。要让你的终端使用它们，这个文件夹必须位于 PATH 的最前面。

帮我添加…（或 设置 › PHP › 在我的终端中使用 Joppa 的 PHP）会在你确认后将以下代码块添加到 shell 配置文件中：

# >>> Joppa (PHP) >>>
export PATH="/Users/you/Library/Application Support/joppa/bin":"$PATH"
# <<< Joppa (PHP) <<<

Shell	修改的文件
zsh	~/.zshrc
bash	~/.bash_profile（macOS）、~/.bashrc（Linux）
fish	~/.config/fish/conf.d/joppa.fish（使用 fish_add_path --prepend）

可以在同一设置中移除该代码块。更改后请打开一个新终端。

未固定版本的项目

设置 › PHP › 未固定版本的项目 用于选择其他地方使用的 PHP：系统 PHP 或 Joppa 的某个版本。

Composer

设置中会显示使用的是哪个 Composer（Joppa 的还是系统自带的）。下载 Composer 会在验证校验和后将其安装到 Joppa 中。