Wiki

.uversionignore

用于将文件排除在 uVersion 跟踪之外的 gitignore 风格语法。包含 UE5 默认配置，以及常见设置的配方。

简介

位于工作区根目录的 .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 中，路径一旦匹配其中任意一个就会被忽略。判定遵循固定的优先级，顺序如下：

保留路径 Plugins/uVersion：始终被忽略（由工具管理的文件夹，以二进制形式分发），即使某条规则试图包含它。
ThirdParty 片段：如果路径的某个片段的名称恰好为 ThirdParty，则该文件永不被忽略。参见 ThirdParty 文件夹。
默认放行的插件前缀（没有源代码的已安装插件的 Binaries/）：永不被忽略。
否则：如果路径匹配文件中的某个模式，则被忽略。

前三个步骤是最终决定：其中任意一个一旦适用，下一步就不会被评估，您的模式也完全不会被查阅。正因如此，无法用更精确的规则去"抵消"其中任何一个。

默认 UE5 模板

以下逐行列出了桌面客户端在 UE5 工作区中 clone 时写入的内容。如果您手动将这段内容复制到现有项目中，请完整复制："IDE"和"Linux 项目生成"两节是最容易被遗漏的，缺少它们会导致每次构建时重新生成的项目文件被跟踪，从而在所有人那里产生冲突。

# 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
*.slnx
*.xcworkspace/
*.xcodeproj/
*.code-workspace
*.suo
*.sdf
*.opensdf
*.opendb
*.ncb
*.user

# Linux project generation (GenerateProjectFiles)
Makefile
.ignore

# 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 或 *.dll，此文件仍会被跟踪。

此例外是无条件的：没有任何规则能忽略 ThirdParty 路径

这不是规则之间谁更精确谁就胜出的优先级问题。"这条路径是否包含 ThirdParty 片段？"这一测试在读取您的任何模式之前就已评估，如果答案为是，该文件即被声明为受跟踪，评估到此为止。您的规则永不被查阅。

因此并不存在用于排除某个 ThirdParty 子树的"显式豁免"：无论多么精确的规则都无法做到。如果您确实必须排除这样一个文件夹，唯一的途径是将其重命名，或将其移出 ThirdParty 的目录结构。

只有一样东西能压过此例外：保留文件夹 Plugins/uVersion，即便位于 ThirdParty 之下也仍被忽略。

该片段必须恰好是 ThirdParty

比较针对的是完整的路径片段，而非名称前缀。名为 ThirdPartyLibs、ThirdParty_Old 或 MyThirdParty 的文件夹不在此列：其内容像其他任何文件一样受您的规则约束，一条 *.dll 规则会将其排除。

这是常见的困惑来源：Source/ThirdParty/Lib/x.dll 被跟踪，Source/ThirdPartyLibs/Lib/x.dll 则不被跟踪。如果您发现某个库没有被发送，请先检查文件夹的确切拼写。

常见配方

带有外部美术源文件的项目（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）显式删除它们。

简介

语法