.uversionignore

简介

位于工作区根目录的 .uversionignore 文件定义了客户端绝不应跟踪、上传或包含在提交中的文件和文件夹。采用 .gitignore 风格语法（一个子集：注释、以 / 结尾的文件夹模式，以及名称/扩展名 glob），由 globset 编译。它不是完整的 gitignore：不支持 ! 否定和锚定。下文记录了一些 Unreal Engine 特有的规则。

该文件在 clone 时由桌面客户端使用默认 UE5 模板自动创建。之后您可以编辑它以适配您的项目。

该文件本身也会被跟踪：如果您编辑并提交它，协作者会在下次 sync 时获取您的更改。这是有意为之：整个工作室共享相同的排除规则。

语法

每行一条规则。空行和以 # 开头的行会被忽略（注释）。

基本模式

模式	效果
foo.txt	树中任何层级下名为 foo.txt 的所有文件
foo/	任何层级下名为 foo 的所有文件夹及其内容（文件夹模式始终在任意深度匹配）
foo	任何层级下名为 foo 的文件或文件夹（无结尾斜杠）

通配符

模式	效果
*.tmp	任何层级下的所有 .tmp 文件
*.{tmp,bak,old}	花括号展开：等同于 *.tmp + *.bak + *.old
foo*	名称以 foo 开头的任何文件或文件夹
?ile.txt	? 恰好匹配一个字符：file.txt、pile.txt 等
[abc].txt	字符类：a.txt、b.txt、c.txt
**/build/	递归：任何层级下的所有 build/ 文件夹（等同于 build/）
Content/**/Tmp/	中间递归：位于 Content/ 下某处的所有 Tmp/ 文件夹
Content/**	Content/ 下的所有内容，任意深度

无否定（!）

与 .gitignore 不同，uVersion 不支持用于重新包含文件的 ! 前缀。以 ! 开头的行会被视为字面模式，而非例外。在被忽略文件夹内重新跟踪文件只能通过自动规则实现：ThirdParty 例外，以及已安装插件的 Binaries/ 白名单（见下文）。

注释

# Build artifacts (regénérés à chaque build, jamais à versioner)
Binaries/
Intermediate/

行中间的 # 不是注释：它是模式的一部分。只有行首（可选空白之后）的 # 才开始注释。

规则优先级

文件中行的顺序无关紧要：所有模式都编译到单个 GlobSet 中，路径一旦匹配其中任意一个就会被忽略。判定遵循固定的优先级，顺序如下：

1. 保留路径 Plugins/uVersion：始终被忽略（由工具管理的文件夹，二进制分发），即使某条规则试图包含它。
2. ThirdParty 组件：如果路径的某个片段的名称恰好为 ThirdParty，则该文件永不被忽略。
3. 白名单插件前缀（已安装插件的 Binaries/）：永不被忽略。
4. 否则：如果路径匹配文件中的某个模式，则被忽略。

默认 UE5 模板

以下正是桌面客户端在 UE5 工作区中 clone 时生成的内容：

# uVersion ignore - Unreal Engine 5 defaults
# Note: Installed plugins, ThirdParty directories, and plugins with
# external library dependencies are automatically whitelisted.

# Build & intermediate (regenerated by UE5)
Binaries/
Build/
DerivedDataCache/
Intermediate/
Packages/
Saved/

# IDE / editor
.vs/
.vscode/
.idea/
.vsconfig
*.sln
*.suo
*.sdf
*.opensdf
*.opendb
*.ncb
*.user

# Build artifacts
*.pdb
*.obj
*.o
*.lib
*.dll
*.so
*.dylib
*.exe
*.exp
*.ilk
*.iobj
*.ipdb
*.pch
*.ipch
*.res
*.tlog
*.manifest

# Logs & temp
*.log
*.tmp
*.bak
*.swp

# OS files
Thumbs.db
.DS_Store
desktop.ini

您可以向此文件添加自己的规则。记得提交它，以便整个工作室拥有相同的排除项。

插件

保留文件夹 Plugins/uVersion

Plugins/uVersion 文件夹（uVersion 插件本身）在任意深度都始终被忽略，且此规则优先于其他一切。它由桌面客户端管理（二进制分发），绝不应被提交。诸如 Plugins/uVersionExtras 之类的相邻文件夹不受影响。

uVersion 还会应用针对其他插件的智能逻辑，无需在文件中写入任何内容：

• 如果某个插件在其 .uplugin 中有 "Installed": true 且没有 Source/ 文件夹（纯二进制插件，Marketplace 类型）→ 其 Binaries/ 会被加入白名单，因此被跟踪。这是正确的：对于二进制插件，编译后的 .dll 就是插件本身。
• 如果插件有 Source/ 文件夹（可重新编译）或没有 "Installed": true → 其 Binaries/ 和 Intermediate/ 会像主项目一样被忽略（二进制文件是构建时重新生成的产物）。

此逻辑无需为从 Epic Marketplace 下载的商业插件手动维护例外。工作室可以混用源代码插件和二进制插件，无需任何配置。

ThirdParty 文件夹

任何包含 ThirdParty/ 的路径都始终被跟踪，即使某条父规则会忽略它。这遵循 Unreal 惯例：ThirdParty/ 通常包含项目编译所需的预编译库（.lib、.dll、.so、.a）。

Plugins/MyPlugin/Source/ThirdParty/SomeLib/lib/Win64/SomeLib.lib

即使您在 .uversionignore 中写入 **/lib/ 或 *.lib，得益于隐式的 ThirdParty/ 规则，此文件仍会被跟踪。

常见配方

带有外部美术源文件的项目（Maya、Blender、ZBrush）

如果您的美术源文件（.blend、.mb、.zpr）位于 UE 项目旁边，您可能想跟踪它们但不想跟踪其缓存：

# Sources d'art (à versionner)
ArtSource/

# Mais pas les caches Blender / Maya
**/blendcache_*/
**/cache/
**/temp/
**/*.blend1
**/*.mb~

带有多个不想提交的测试地图的项目

# Maps de test temporaires (chacun les sien sur son disque)
Content/Maps/Test_*.umap
Content/Maps/Test_*.uasset

在通用规则下仍跟踪特定二进制文件

由于不存在否定 !，无法全局排除 *.exe/*.dll 后再重新包含某个二进制文件。请改为将一次性产物放在被忽略的文件夹下（例如 Intermediate/），并将想跟踪的工具保持在排除模式之外。Unreal 替代方案：构建库属于 ThirdParty/，它始终被自动跟踪。

忽略个人笔记

# Chacun ses notes
notes.md
TODO.txt
.scratch/

带有中间打包产物的跨平台项目

# Packagés (publish via le client, pas dans le repo)
Packages/
Saved/StagedBuilds/

# Caches de cook par plateforme
Saved/Cooked/
Build/Win64/
Build/Mac/
Build/Linux/

测试文件

要在提交前检查某个路径是否会被客户端忽略，请使用 CLI：

$ uversion status MaybeIgnored/File.uasset
# Si le fichier apparaît dans la sortie → il est tracké
# S'il n'apparaît pas (et qu'il existe sur disque) → il est ignoré

或者更直接地，以 JSON 模式配合 jq 过滤器：

$ uversion status --json | jq '.files[] | select(.path == "MaybeIgnored/File.uasset")'

常见陷阱

结尾斜杠 = 文件夹，无斜杠 = 含糊

foo 会同时忽略文件 foo 和文件夹 foo/。foo/ 仅忽略文件夹。如果您想精确，请为文件夹加上结尾斜杠。

区分大小写

模式区分大小写。Content/ 不匹配 content/。由于 Windows 在文件系统层面不区分大小写，如果一位 Windows 上的开发者命名为 Content/ 而另一位命名为 content/，您可能会遇到无声的冲突。请统一为 Content/。

无法重新包含（!）

写入 !Saved/Config/Foo.ini 不会重新包含任何内容：不支持否定，该行会被当作字面模式。要保留某个子文件夹，请只忽略您想排除的子树（例如 Saved/Logs/、Saved/Backup/），而不是整个 Saved/。

过于宽泛的模式

*.zip 会忽略工作区中的所有 .zip，包括有意命名为 .zip 的游戏资产（罕见，但在冒险游戏 / 数据文件中会出现）。请优先使用更具体的模式：dist/*.zip、Releases/*.zip 等。

编辑 .uversionignore 不影响已提交的文件

与 git 一样，向 .uversionignore 添加模式不会使已跟踪的文件消失。如果您想将它们从仓库中移除，必须通过桌面客户端（Mark for delete + checkin）显式删除它们。