php如何创建一个phar归档文件 php Phar打包应用与部署方法

下次还敢

发布时间：2025-09-14 18:16:01

813人浏览过

来源于php中文网

原创

PHAR归档文件能将PHP项目打包成单个自包含文件，极大简化部署流程。它解决了传统部署中依赖管理复杂、环境不一致、回滚困难等问题，特别适用于CLI工具和小型Web应用。通过Phar类创建PHAR时需关闭phar.readonly，使用buildFromDirectory打包代码与依赖，并设置stub作为执行入口。优势包括：单文件部署省去git clone和composer install；环境一致性避免“在我机器上能运行”的问题；版本化PHAR便于回滚；分发便捷，用户仅需PHP解释器即可运行。注意事项有：必须手动处理外部配置与日志路径；__DIR__和__FILE__在PHAR内指向虚拟路径；stub中引用内部文件需用phar://协议；建议打包后开启phar.readonly提升安全性。CI/CD中可自动化构建PHAR并结合符号链接实现平滑部署，也可集成进Docker镜像实现容器化交付。

php如何创建一个phar归档文件 php phar打包应用与部署方法

PHP的PHAR归档文件，在我看来，就是PHP世界里的一个自包含（self-contained）应用包，它能把你的整个PHP项目，包括代码、资源文件甚至第三方依赖，都打包成一个独立的文件。这对于应用的部署和分发简直是福音，尤其是那些CLI工具或小型Web应用，部署时只需要简单地复制这一个文件就行了。它极大地简化了传统PHP项目部署时繁琐的

git pull

、

composer install

等步骤，让应用的交付变得异常高效和优雅。

解决方案

要创建一个PHAR归档文件，我们首先需要确保PHP环境允许写入PHAR文件。这通常意味着在

php.ini

中将

phar.readonly

设置为

Off

。完成打包后，出于安全考虑，我会建议再将其改回

On

。

核心的打包过程主要依赖PHP内置的

Phar

类。下面是一个典型的打包流程示例，它会把一个简单的PHP应用打包进去：

假设我们有一个名为

my-app

的目录结构：

立即学习“PHP免费学习笔记（深入）”；

my-app/
├── src/
│   └── greeter.php
├── vendor/
│   └── autoload.php
│   └── ... (Composer dependencies)
├── config/
│   └── app.php
└── cli-tool.php

其中

cli-tool.php

可能是应用的入口文件，

greeter.php

是业务逻辑，

vendor

是Composer依赖。

打包脚本示例 (

build.php

buildFromDirectory($appDir, '/^((?!build\.php).)*$/'); // 排除打包脚本自身

    // 3. 设置应用的启动器（stub）。这是PHAR文件被执行时最先运行的代码。
    // 通常，它会包含Composer的自动加载器和你的应用入口点。
    $phar->setStub($phar->createDefaultStub('cli-tool.php'));

    // 4. (可选) 压缩PHAR文件，可以减小体积
    // $phar->compressFiles(Phar::GZ); // 使用Gzip压缩
    // $phar->compressFiles(Phar::BZ2); // 使用Bzip2压缩

    // 5. (可选) 设置PHAR的元数据，比如版本信息
    $phar->setMetadata(['version' => '1.0.0', 'build_date' => date('Y-m-d H:i:s')]);

    echo "PHAR文件 '{$pharFile}' 创建成功！\n";

} catch (Exception $e) {
    echo "创建PHAR时发生错误: " . $e->getMessage() . "\n";
    exit(1);
}

// 完成后，你可以考虑将phar.readonly改回On，以提高安全性
// ini_set('phar.readonly', 'On'); // 这行代码在打包脚本中执行意义不大，需要手动修改php.ini

运行这个

build.php

脚本，你就会得到一个

my-app.phar

文件。部署时，只需将这个文件复制到目标服务器，然后通过

php my-app.phar

来执行你的CLI工具，或者通过Web服务器配置来运行它（虽然CLI场景更常见）。

如果你的应用入口文件不在根目录，或者需要更复杂的启动逻辑，

createDefaultStub()

可能不够用。这时，你可以手动编写一个stub文件，例如：

// stub.php

然后，在打包脚本中这样设置stub：

$phar->setStub(file_get_contents('stub.php'));

。

Thiings

免费的拟物化图标库

下载

PHAR打包能解决哪些痛点，它比传统部署方式有哪些优势？

在我看来，PHAR打包最核心的价值在于它提供了一种“单文件部署”的能力。这真的太省心了。回想一下传统的PHP应用部署流程：

git clone

，然后

composer install

，可能还需要配置Web服务器的根目录、权限等等。这个过程在开发环境和生产环境之间总会有一些细微的差异，甚至因为网络问题导致

composer install

失败，或者某个依赖版本不兼容。

PHAR直接把这些问题都解决了。

简化部署：最大的优势。你只需要复制一个文件到服务器，就这么简单。这对于自动化部署脚本来说简直是天赐之物，因为你不需要关心服务器上是否安装了Git、Composer，也不用处理权限或路径问题。
环境一致性：PHAR文件内部包含了所有依赖，这意味着它在打包时的环境是什么样，部署后执行的环境基本就是什么样。这大大减少了“在我机器上跑得好好的”这种尴尬情况。
版本控制与回滚：部署新版本时，只需替换PHAR文件。如果新版本有问题，回滚也只是替换回旧版本的PHAR文件，操作成本极低。
分发便利性：如果你开发了一个PHP CLI工具，想要分发给其他人使用，PHAR是最佳选择。他们不需要搭建完整的PHP开发环境，只需要一个PHP解释器就能运行你的工具。
安全性（部分）：PHAR文件可以被签名，以确保其完整性和来源。此外，一旦打包完成，如果将
```
phar.readonly
```
设置为
```
On
```
，PHAR文件内容就无法被修改，这在一定程度上增加了安全性。

当然，PHAR也不是万能药，它有自己的适用场景。对于大型Web应用，特别是那些需要频繁更新、大量静态资源（图片、CSS、JS）或动态生成内容的场景，PHAR可能就不是最优解了。但对于CLI工具、微服务或者一些后端服务，它的优势非常明显。

PHAR打包时常见的坑和注意事项有哪些？

我自己在实际使用PHAR的过程中，也踩过一些坑，总结下来有这么几点，我觉得特别值得注意：

phar.readonly
这个“拦路虎”：这是新手最常遇到的问题。PHP为了安全，默认情况下是禁止写入PHAR文件的。所以，在打包之前，务必在
```
php.ini
```
里把
```
phar.readonly
```
设为
```
Off
```
。我见过不少人打包失败，然后一脸懵逼，最后才发现是这个配置在作怪。打包完成后，我个人习惯是把它改回
```
On
```
，毕竟安全性还是要考虑的。
Stub文件的编写：Stub是PHAR的“大脑”，它决定了PHAR文件被执行时会发生什么。
```
createDefaultStub()
```
虽然方便，但如果你的应用入口比较复杂，或者需要自定义一些初始化逻辑（比如加载环境变量），你就得手写一个stub。这里的关键是，所有对PHAR内部文件的引用都必须使用
```
phar://
```
协议，比如
```
require 'phar://' . __FILE__ . '/path/to/file.php';
```
。少了
```
phar://
```
，PHP会去文件系统里找，那肯定找不到。
外部文件处理：PHAR是一个自包含的包，但很多应用需要读写外部文件，比如配置文件、日志文件、上传文件等。这些文件显然不能被打包进PHAR，因为PHAR是只读的。我的做法通常是，在应用启动时，通过环境变量或命令行参数指定这些外部文件的路径，或者在PHAR旁边创建一个数据目录。记住，PHAR内部的代码是无法直接写入PHAR文件本身的。
性能考量：虽然PHAR通常会比解压后的文件系统访问稍快（因为减少了文件查找开销），但如果PHAR文件非常大，或者包含了大量小文件，IO操作可能会有轻微的开销。此外，PHP的OPcache对PHAR的支持非常好，可以显著提升性能，所以确保你的生产环境开启了OPcache。
__DIR__
和
__FILE__
的陷阱：在PHAR内部，
```
__DIR__
```
和
```
__FILE__
```
的行为会有点特殊。它们会指向PHAR文件内部的虚拟路径，而不是宿主文件系统的路径。这在处理相对路径时需要特别小心。通常我会通过PHAR的stub文件来获取PHAR自身的真实路径，然后根据这个路径来构建外部资源的绝对路径。
Composer依赖的打包：
```
buildFromDirectory
```
通常能很好地处理
```
vendor
```
目录。但如果你有post-install脚本或者其他Composer插件，需要确保它们在打包时不会引起问题。最稳妥的方式是，在打包前先运行
```
composer install --no-dev
```
，确保
```
vendor
```
目录是干净且完整的。
Web服务器的配置：如果你想通过Web服务器（如Nginx或Apache）直接运行PHAR文件，需要一些额外的配置。通常是把PHAR文件当作一个PHP脚本来处理。例如，Nginx配置中可能需要
```
fastcgi_pass
```
到PHP-FPM，并且确保
```
SCRIPT_FILENAME
```
变量指向PHAR文件。但说实话，Web应用直接运行PHAR的情况相对较少，CLI工具用PHAR更普遍。

PHAR应用在不同部署环境下的实践策略是什么？

部署PHAR应用，我发现最核心的理念就是“少即是多”。一个文件搞定一切，这本身就是最大的策略。

CI/CD自动化集成：这是我最推荐的方式。将PHAR的打包过程集成到你的持续集成/持续部署（CI/CD）流程中。当代码合并到主分支时，CI服务器（比如Jenkins、GitHub Actions、GitLab CI）会自动执行打包脚本，生成PHAR文件。
- 构建阶段：在CI环境中，首先拉取代码，运行
```
composer install --no-dev
```
  ，然后执行我们前面提到的
```
build.php
```
  脚本来生成
```
.phar
```
  文件。
- 产物存储：生成的
```
.phar
```
  文件作为构建产物，可以上传到制品库（如Artifactory、S3）或直接作为CI/CD管道的下一个阶段的输入。
- 版本管理：通常我会给PHAR文件命名加上版本号或Git commit hash，比如
```
my-app-1.0.0.phar
```
  或
```
my-app-abcdef1.phar
```
  ，这样可以方便回溯和管理不同版本。
部署策略：
- 直接复制：最简单粗暴但也非常有效的方式。通过
```
scp
```
  、
```
rsync
```
  或者CI/CD工具的部署Agent，直接将PHAR文件复制到目标服务器的指定目录。
- 符号链接（Symlink）：在部署新版本时，可以先将新的PHAR文件复制到一个带有版本号的目录（例如
```
/opt/my-app/releases/1.0.0/my-app.phar
```
  ），然后更新一个指向当前活动版本的符号链接（例如
```
/opt/my-app/current/my-app.phar
```
  ）。这样回滚就变得异常简单，只需将符号链接指回旧版本即可。
- 容器化部署：对于更现代的部署方式，可以将PHAR文件打包进Docker镜像。Dockerfile会非常简洁，只需要一个基础PHP镜像，然后将PHAR文件复制进去，并设置好入口点（
```
ENTRYPOINT
```
  ）为
```
php my-app.phar
```
  。这提供了极致的环境隔离和可移植性。
生产环境配置与运行：
- CLI工具：这是PHAR最常见的应用场景。部署后，直接通过
```
php /path/to/my-app.phar [arguments]
```
  来执行。确保服务器上的PHP解释器版本与打包时的PHP版本兼容。
- Web服务：虽然不如CLI常见，但也不是不可能。如果你的PHAR是一个简单的API服务或Web钩子，可以配置Web服务器（如Nginx）将其作为PHP脚本来处理。关键在于Nginx的
```
fastcgi_pass
```
  配置，需要正确地将请求传递给PHP-FPM，并确保
```
SCRIPT_FILENAME
```
  变量指向你的
```
.phar
```
  文件。不过，我个人倾向于将这类Web服务用更传统的PHP-FPM + 目录结构来部署，或者干脆用Swoole/RoadRunner这类异步框架来构建，PHAR在这方面优势不那么明显。
- 日志与配置：在部署时，要确保PHAR应用能够正确访问外部的日志目录和配置文件。这通常通过环境变量或命令行参数在启动PHAR时传入。例如，
```
php my-app.phar --config=/etc/my-app/config.php --log-dir=/var/log/my-app
```
  。