---
url: https://docs.zblogcn.com/php/guide/zbignore.md
description: >-
  介绍 Z-BlogPHP 应用目录中 zbignore.txt 打包排除清单的语法、默认排除项与工作方式，用于在打包 .zba
  安装包时排除不需要分发的文件和目录。
---

# Z-BlogPHP zbignore.txt 参考

`zbignore.txt` 是放在 Z-BlogPHP 应用（插件或主题）目录根下的打包排除清单，作用类似开发中常见的 `.gitignore`：打包 `.zba` 安装包时按行读取其中的规则，命中的文件或目录不会进入安装包。该特性自 1.6 版本起提供，适合用来排除开发临时文件、本地文档等不需要分发给用户的内容。

## 文件位置

`zbignore.txt` 放在应用目录的根下，与 `插件名.php` 或 `theme.xml` 等应用信息文件同级，例如：

* 插件：`zb_users/plugin/应用ID/zbignore.txt`
* 主题：`zb_users/theme/应用ID/zbignore.txt`

打包应用时才会读取这个文件，它不影响程序的日常运行。

## 语法规则

文件内容为逐行书写的 glob 模式，每行一条规则，匹配对象是**相对应用根目录的路径**：

* 空行会被忽略，其余每行都作为一条规则参与匹配；
* 模式遵循 PHP `fnmatch()` 的通配符：`*` 匹配任意长度字符，`?` 匹配单个字符，`[abc]` 匹配方括号内的任一字符，`[!abc]` 匹配方括号之外的字符；
* `*` 可以跨越目录层级，例如 `*.log` 能匹配所有子目录中的 `.log` 文件；
* 规则命中一个实际存在的目录时，整个目录连同其中的文件都会被排除，写 `docs`、`docs/` 均可；
* `zbignore.txt` **不支持注释**，以 `#` 开头的行同样会被当作规则处理。

例如，应用目录下有本地文档、日志和设计稿，不想随应用分发：

```text
docs
*.log
*.psd
```

上面三条规则分别表示：排除整个 `docs` 目录；排除所有 `.log` 文件；排除所有 `.psd` 文件。

## 默认排除的文件

以下文件无需写入 `zbignore.txt`，打包时默认就会排除：

* `.gitignore`
* `.DS_Store`
* `Thumbs.db`
* `composer.lock`
* `zbignore.txt`（自身不会打进包）
* `*.code-workspace`

此外，通过后台应用中心的「导出」功能打包时，还会自动排除更新标记文件 `app_update.lock`。

## 与应用更新的关系

被排除的文件不会出现在 `.zba` 安装包中，也就不会包含在后续分发的更新包里。站点上由用户自行放置或替换的同名文件（如替换过的 logo、favicon、二维码等「替代性」文件）因此不会被更新覆盖。应用开发中的相关建议见「[常见问题（应用开发）](/php/dev-faq)」。

打包前请检查规则，避免误伤程序运行必需的文件——被排除的文件在用户的站点上将随安装包缺失。
