从“文件夹没删”看发布流程自动化：目录清理与构建检查实践

最近《洛克王国》相关话题里冒出一句“工程师偷懒，文件夹没删”，看着像段子，但在游戏开发和项目交付里，这真不是小事。一个本该清理掉的文件夹如果混进正式发布包，轻则包体变大、加载变慢，重则测试配置暴露、内部资源泄漏、线上功能异常。本文就用技术复盘的方式聊一聊：这类“文件夹没删”的问题是怎么发生的、会造成哪些影响、用什么手段能在交付前自动拦住它。

重点不是调侃某个人，而是把这件事当工程问题拆开。我会从目录结构、构建流程、版本控制、发布检查、自动化流水线几个层面展开，最后给出一套可落地的清理规范和排查清单。无论你是在做游戏项目、小程序、Web 前端还是后端服务，“发布前目录没清干净”的坑都有可能出现。

1. “文件夹没删”到底是什么级别的问题

从工程角度看，这不是一句“粗心”就能带过的。它属于典型的版本交付事故。无论是游戏客户端、网站静态资源还是后端服务包，最终交付的目录结构往往和开发目录不完全一致。开发期为了调试方便，会有测试资源、本地配置、临时代码、自动化工具、日志文件等。正常情况下，这些内容需要从发布目录中隔离出去。

如果某个文件夹被误带入正式环境，通常会造成三类问题：

第一类是包体膨胀。一个包含大量美术资源、地图数据或测试视频的文件夹可能占用几十 MB 甚至几个 GB，最终影响下载安装包大小、更新包体积和启动加载速度。

第二类是功能异常。测试资源目录里可能包含与正式环境不匹配的配置、覆盖用的本地数据、临时代码占位文件。客户端运行时可能加载到错误路径，出现界面错乱、模型加载失败、接口地址指向内网等状况。

第三类是信息泄露。开发期文件夹里常出现内网配置、测试账号、日志文件、截图素材、未公开活动内容等。这些内容一旦进入玩家可访问的发布包，等于把内部工作信息直接暴露给了用户和竞争对手。

所以，“文件夹没删”表面上只是少做了一步删除操作，实际上暴露出三个工程问题：发布流程没有规范化、交付前的目录检查缺失、版本控制或构建脚本没有做好隔离。

2. 事故影响面速览

先给出一张通用影响面表格，方便读者快速评估这类事故的严重程度。不同项目文件夹不同，但表格里的检查思路可以直接套用。

这张表不只是针对游戏项目，任何有“构建产物”和“源码头”两个目录的项目都适用。

3. 为什么这种问题特别容易出现在游戏项目里

游戏项目的目录结构比一般应用更复杂。以常见的客户端项目为例，工程里会同时存在：

• 引擎工程目录，存放场景、预制体、材质球。
• 美术资源目录，存放模型、贴图、动作、特效。
• 策划配置目录，存放数值表、任务表、活动表。
• 测试专用目录，存放自动化测试脚本、本地调试素材。
• 运营目录，存放活动海报、礼包配置、公告文案。
• 日志目录，存放开发期运行日志、崩溃日志、性能数据。

这些目录在开发机上是并列关系，但在打包发布时，并不是所有内容都应该进入玩家客户端。有一个很常见的操作，就是美术或策划同学在开发目录里建立一个“测试用”文件夹，里面放几张临时贴图、一段演示动画、一份未完成的策划表。这类临时文件夹往往不会记录在版本管理仓库里，因为属于本机调试内容。但只要打包人直接在开发机上执行资源收集和打包命令，它就有几率被一起收进去。

另外，游戏版本更新频繁，客户端经常需要做增量包、补丁包、热更包。多版本并行开发时，如果构建目录是复制上一版目录再修改，就很容易把上一版的临时文件夹一起复制过来。时间一长，构建服务器上的目录会积累大量“历史遗留”文件。

这里还有一个容易被忽略的点：游戏项目的资源命名和目录结构不一定有强制规范。如果团队只约定“不要放无关文件”，而没有用脚本或检查步骤兜底，最后就只能靠打包人当时的记性。人一旦在赶版本，记性最容易失效。

4. 一个典型案例：目录结构、构建流程、版本控制

为了后面讲验证方法，我先构造一个通用的游戏项目发布场景。假设项目目录大致如下：

text复制game_project/
├── Assets/                 # 主资源目录
│   ├── Scripts/
│   ├── Art/
│   ├── Config/
│   └── TestResources/      # 开发期测试资源
├── Build/                  # 构建输出目录
│   ├── Windows/
│   └── Android/
├── Packages/
├── ProjectSettings/
├── Tools/
├── temp_upload/            # 临时上传目录
├── internal_docs/          # 内部文档
└── .gitignore

正常流程是这样的：开发在 Assets 里提交代码和正式资源，TestResources 只用于本地调试，不应进入最终包。temp_upload 是发给运营的临时目录，也应该从客户端资源中排除。internal_docs 更不用说，里面往往有未公开的活动方案和服务器配置。

一次典型的错误发布流程可能长这样：

1. 开发人员在本地改完资源，把 Assets 整体复制到打包机的 Build 目录。
2. 打包机执行资源导入和打包脚本。
3. 脚本只会收集主目录下所有资源，不做排除。
4. 打完包后，TestResources、temp_upload、internal_docs 全部跟着进入客户端资源目录。
5. 版本质检只关注玩法功能是否正常，没检查包内目录。
6. 包体上传到 CDN，玩家下载更新，问题爆发。

从目录结构看，问题不在某一帧动画或某个脚本，而是整个“文件夹边界”没有守住。版本控制系统里如果也没有完整的清理规则，那这个问题会反复出现。

4.1 版本控制层面的缺失

很多团队会把 .gitignore 配得过于简单，只忽略 Build/、temp_upload/，但忽略 TestResources 这种带“测试”二字的目录。开发人员发现这些目录没有变化，就不会主动提交删除请求。即使有人想起来清理，也会因为没有明确的负责人而搁置。

正确的做法，是在仓库根目录维护一份明确的“不发布目录”清单，同时在构建脚本中强制排除。也就是说，不能只靠个人意志，而要让流程自动完成。

5. 环境准备与前置条件

这会涉及项目发布前的基础设施检查，不限于游戏项目。如果以本地构建流程为例，需要准备以下内容。

环境准备不是只写一份文档，而是应该在构建机上通过脚本做自动检查。比如构建前先检查磁盘空间，低于阈值就退出，不要等到打完包才发现空间不够。

5.1 通用检查命令

下面是一个常见的目录清理检查模板。实际使用时需要把 PROJECT_ROOT、CHECK_DIRS 替换成真实路径。

bash复制#!/usr/bin/env bash
# 通用发布前目录检查脚本，按实际项目路径调整
PROJECT_ROOT="/data/projects/game_project"
CHECK_DIRS=("Assets/TestResources" "temp_upload" "internal_docs")
FOUND=0

for dir in "${CHECK_DIRS[@]}"; do
    if [ -d "${PROJECT_ROOT}/${dir}" ]; then
        echo "[ERROR] 发现不应发布目录：${dir}"
        FOUND=1
    else
        echo "[OK] 目录已清理：${dir}"
    fi
done

if [ ${FOUND} -eq 1 ]; then
    echo "构建中止，请先清理上述目录。"
    exit 1
fi

echo "目录检查通过。"
exit 0

这段脚本的作用是在构建前扫描固定目录黑名单。如果黑名单目录仍然存在，直接中止构建。看起来简单，但能避免大量低级失误。

6. 部署与启动方式：从构建到发布的目录清理流程

这里所说的“部署”不是游戏客户端的安装过程，而是指构建产物从仓库到发布包的流转过程。整个过程建议按六步走。

6.1 第一步：拉取干净代码

不要使用本地开发环境作为构建目录，而是在构建机上重新从版本库拉取最新代码。这样可以避免开发机上的临时文件混入。

bash复制cd /data/projects
rm -rf game_project
git clone git@host:game_project.git
cd game_project
git checkout release/1.0.0

6.2 第二步：执行目录预清理

参照上一节，先运行一次黑名单目录扫描。如果发现任何不应该存在的目录，立即退出。

bash复制bash pre_build_check.sh

6.3 第三步：标准化资源收集

游戏项目通常会有一个资源收集脚本来决定哪些文件进入包。在脚本里增加排除列表，而不是简单复制整个 Assets。

bash复制# 示例：资源收集时排除临时目录，按项目实际脚本调整
python collect_assets.py \
    --source Assets \
    --output Build/Assets \
    --exclude Assets/TestResources \
    --exclude temp_upload \
    --exclude internal_docs

6.4 第四步：打包构建

构建工具执行资源和代码的编译打包。这一步需要确保生成目录是独立目录，不能用上一次的残余产物。

bash复制# 清理上次构建产物，路径按项目调整
rm -rf Build/Windows
mkdir -p Build/Windows

# 执行构建命令，按具体引擎或工具调整
python build_game.py --platform Windows --output Build/Windows

6.5 第五步：产物目录复核

打包完成后，不依赖任何人“对一下”，而是再跑一次产物扫描，确认发布包中不含黑名单文件。

bash复制find Build/Windows -type d -name "TestResources" -o -type d -name "internal_docs"

如果扫描结果为空，说明清理成功。如果不为空，说明构建脚本有问题，需要回炉。

6.6 第六步：产物签名与上传

发布包确认没问题后，再执行签名、加密、上传 CDN 或商店操作。这一步要与构建步骤分离，只有前一步成功后才会触发。

bash复制# 假设存在 upload 脚本
python upload_build.py --file Build/Windows/game_pkg_1.0.0.zip --channel official

以上六步流程可以用本地脚本串起来，也可以放到 CI 流水线里执行。从“人记得删目录”变成“流程检查发现目录”，错误概率会显著下降。

7. 功能测试与效果验证：发布前目录完整性检查

发布前的验证不能只靠肉眼看界面。至少要做四个维度的检查。

7.1 目录白名单检查

发布包内目录结构应满足白名单要求。允许出现的目录列表由项目定义，其余一律视为异常。下面是一个简化版 Python 扫描脚本，可以输出在发布目录中发现的黑名单关键字。

python复制import os
from pathlib import Path

# 通用示例，请按实际项目替换路径和黑名单
PUBLISH_ROOT = Path("./Build/Windows")
BLACK_KEYWORDS = [
    "TestResources",
    "temp_upload",
    "internal_docs",
    "debug",
    "mock",
]

def scan_black_dirs(root: Path) -> list:
    black_found = []
    for path in root.rglob("*"):
        if path.is_dir():
            for keyword in BLACK_KEYWORDS:
                if keyword.lower() in path.name.lower():
                    black_found.append(str(path))
                    break
    return black_found

if __name__ == "__main__":
    found = scan_black_dirs(PUBLISH_ROOT)
    if found:
        print("发现不应存在的目录：")
        for item in found:
            print(" -", item)
        exit(1)
    print("目录检查通过。")

7.2 文件清单比对

发布包中的文件清单应与版本库中的正式文件清单做 diff。构建产物会有编译生成的新文件，但核心资源文件不应有“版本库里未记录的新增目录”。

bash复制# 生成版本库文件清单
git ls-files > /tmp/repo_files.txt

# 生成发布包文件清单
find Build/Windows -type f > /tmp/build_files.txt

# 对比并筛选新增内容
comm -13 /tmp/repo_files.txt /tmp/build_files.txt | head -n 50

注意这个命令只是思路示例，实际发布包会包含新生成的二进制和元数据，不能直接当成最终结论。重点是对比新增文件里是否出现了本不该存在的目录前缀。

7.3 敏感信息扫描

在发布包内扫描 IP 地址、内网域名、测试账号等敏感字符串。如果发现任何相关内容，立即阻断发布。

bash复制# 示例：扫描发布目录中的内网 IP 和内网域名
grep -rE "(192\.168\.|10\.0\.|127\.0\.0\.1|test\.internal|debug\.)" Build/Windows

这里要注意，扫描结果需要人工复核，因为有些资源内容可能会合法包含示例 IP。但既然能扫出来，就说明发布前缺少过滤环节。

7.4 包体体积趋势对比

记录每次发布包的体积，建立趋势表。如果某次发布包体积突然增加了几百 MB，即使功能测试正常，也要回查是否混入多余资源。

bash复制du -sh Build/Windows

从工程实践看，目录泄漏往往最先反映在包体体积上。所以包体体积监控是最简单也最有效的一道防线。

8. 用接口/流水线做批量检查：自动化防线

如果团队有 CI/CD 服务，推荐把目录检查变成一个自动化步骤，而不是只在本地跑一次。这样可以覆盖多人多次提交，也不会再依赖“某个人的自觉”。

8.1 把检查脚本接入 CI

例如在 GitLab CI 或 Jenkins 中增加一个 build-check 流水线阶段。代码示意的伪配置如下：

yaml复制stages:
  - check
  - build

directory-check:
  stage: check
  script:
    - bash pre_build_check.sh
  only:
    - tags

当执行 git tag release-1.0.0 时，流水线会先拉起目录检查步骤。一旦检查失败，后续构建不会执行。

8.2 提供接口 API 给发布平台调用

如果你不希望在 CI 里写死目录，而是希望运营平台在发起发布申请时自动触发一次“目录体检”，可以给检查逻辑封装成一个 HTTP 接口。

下面是一个通用的服务端思路，实际接口需要按项目技术栈实现，不要直接照抄。

python复制from flask import Flask, request, jsonify
import subprocess

app = Flask(__name__)

@app.route("/api/check-publish-dir", methods=["POST"])
def check_publish_dir():
    data = request.get_json()
    build_path = data.get("build_path", "")

    # 调用前面写的黑名单扫描脚本，路径需替换
    result = subprocess.run(
        ["python", "scan_publish_dir.py", build_path],
        capture_output=True,
        text=True
    )
    if result.returncode == 0:
        return jsonify({"code": 0, "message": "目录检查通过", "detail": result.stdout})
    return jsonify({"code": 1, "message": "目录检查失败", "detail": result.stdout + result.stderr})

if __name__ == "__main__":
    app.run(host="127.0.0.1", port=8008)

这个接口只接受受信任的调用方，最好放在内网环境。不要把这类检查接口直接暴露到公网。接口返回结果是结构化 JSON，后续可以继续接公司内部的发布审批系统。

8.3 批量任务：多项目定时扫描

如果你手上不止一个游戏项目，建议把目录扫描做成一个定时批量任务。每天扫描所有项目目录，输出“风险目录清单”并发到团队群。这样即使某个项目发布时漏查，后续也能及时发现。

bash复制# 示例定时任务
0 2 * * * /usr/bin/python3 /data/tools/scan_all_projects.py /data/projects --output /data/scan_result.json

批量任务要注意失败的幂等性：重复运行不会产生额外污染，失败后恢复时可以重新扫描。这类扫描任务本身不应修改项目目录，只做只读分析。

9. 资源占用与性能观察

文件夹没删带来的最直接影响之一，就是资源占用。以下三个指标最值得关注。

9.1 磁盘占用

一个被遗忘的测试资源文件夹，在开发机上可能只有几 MB，但如果里面包含了未压缩的视频、音频、模型文件，几十 GB 也正常。用以下命令可以快速定位大目录。

bash复制du -h --max-depth=2 /data/projects/game_project | sort -rh | head -n 20

在发布机或者说构建机上，建议定期清理历史构建产物，只保留最近 3 到 5 次。否则构建目录会像滚雪球一样越堆越多，最后磁盘爆满，流水线直接挂掉。

9.2 包体体积

包体膨胀不只是下载耗流量，还会影响用户更新率。很多玩家会在弱网环境下停止下载，所以百 MB 级别的异常增量会直接拉低版本覆盖率。如果发布前没有体积对比，这类问题只能等线上数据被动暴露。

建议每次构建后自动输出包体体积和 MD5，与上一次构建结果对比：

bash复制sha256sum Build/Windows/game_pkg_1.0.0.zip > checksum.txt
ls -lh Build/Windows/game_pkg_1.0.0.zip

9.3 加载耗时

客户端启动时会遍历资源目录生成索引。如果包内多出大量无关文件夹，资源导入和索引生成时间会变长。这个问题在开发机上可能不明显，但在玩家低配设备上会非常敏感。

观察方式：在同样设备上，分别用正常包和“异常包”启动游戏，记录冷启动时间。如果时间差超过 20%，就要怀疑异常包里的多余文件拖慢了索引流程。

10. 常见问题与排查方法

当“文件夹没删”已经发生时，线上玩家可能已经下载了异常包。这时处理步骤要快，先止血再根治。下面给出一张常见问题排查表。

如果异常包已经上线，优先下架问题版本、回滚到上一稳定包。然后保留异常包用于复盘，不要直接覆盖删除。分析出真实原因后，修好构建脚本再发布新版本。

11. 最佳实践与使用建议

把“文件夹没删”这类问题彻底防住，要从规范、流程、自动化三个层面同时下手。

11.1 规范层面：明确目录边界

每个项目必须在文档里写清楚：哪些目录属于正式资源、哪些目录只在开发期存在、哪些目录禁止进入版本库。目录命名要统一，例如测试资源统一放在 Assets/TestResources，临时文件统一放在 temp_local。这样扫描脚本只需要维护一组关键词，不用每个目录挨个看。

11.2 流程层面：发布动作必须走工具

禁止任何人手动复制目录到构建机。所有发布动作都从容器或 CI 流水线触发，从拉代码到资源收集到打包，每一步都有明确日志。只要发布动作还需要人“记得”做某件事，就存在再次出错的可能。

11.3 自动化层面：三层防御

第一层是构建前检查，黑名单目录存在就中止构建。第二层是发布前检查，针对产物目录做白名单校验和敏感信息扫描。第三层是发布后监控，对比包体体积、线上崩溃率、启动耗时。

这三层防御可以配合团队规模来选择。小团队至少要有第一层，中大型团队建议三层全部接入。

11.4 合规与版权提醒

如果团队在开发期放置了未授权的素材、第三方美术资源、测试用的人物照片或声音文件，那么“文件夹没删”可能不仅是技术事故，还会带来版权和隐私风险。在做发布前目录检查时，尤其要筛查人脸、声音、知名 IP 素材、真实用户数据等敏感内容。没有授权确认的资源禁止进入发布包。

11.5 保留一份最小可运行发布配置

把一次干净发布的完整目录树导出为模板，作为所有新项目、新版本构建的基线。后续任何一次构建，都应该尽量贴近基线。如果某个版本为了特殊需求加了目录，要在发布说明中明确写出原因和过期时间。

12. 总结与下一步

“洛克王国工程师偷懒，文件夹没删”这个热点可以作为一次很好的工程复盘素材。它真正值得关注的地方不是某一个人的失误，而是发布流程里缺少检查、缺少自动化、缺少目录边界管理。先检查自己项目的构建脚本里是否有黑名单目录扫描，再对照发布产物做一次文件清单 diff，最后把敏感信息扫描和包体体积监控接入流水线。

最容易踩的坑是：开发环境能跑通、打包环境能跑通，但发布目录里藏着完全不相干的文件夹。先用最小成本保护起来，也就是写一个简单的目录黑名单脚本，放在构建流程最前面。后续再做更细致的产物校验和敏感信息扫描。

如果这篇文章里的目录结构、脚本示例让你产生了一点“这种情况好像在项目里见过”的感觉，那趁早把清理脚本补上。建议收藏备用，等下次发布之前统一查一遍。