在FPGA这一行待久了你会慢慢发现一个有点“反直觉”的现象你花几个月写出来的RTL代码真正有价值的源文件加起来可能不到几百KB但Vivado工程文件夹里跑一次综合、一次实现之后体积轻轻松松冲到几个GB里面全是.runs、.cache、.hw这类中间产物。给同事交付源码时、往Git仓库里提交时、换台电脑继续开发时那堆巨大的工程目录往往比代码本身更让人头疼。这篇文章要解决的就是Vivado工程“大瘦身”这个实际得不能再实际的问题。核心思路其实很古典用 write_project_tcl 把整个工程的定义、源文件引用、约束、IP配置全部写进一个只有几KB的TCL脚本里之后无论在哪个环境只要拿这个脚本配合原始源码就能一键还原出完整工程。这套方案特别适合做版本管理、跨机开发、交付源码的FPGA开发者尤其是被工程体积反复折磨、却又不想放弃Vivado丰富GUI功能的那批人。下面我会从“哪些文件能删、哪些文件不能删”讲起逐步拆解TCL脚本生成、清洁压缩、一键还原、常见问题排查最后再聊聊如何把这一套玩成自动化工作流。所有命令和步骤都是我在实际项目中反复验证过的跟着走基本不会踩坑。1. 为什么Vivado工程会膨胀到几个G先分清能删与不能删1.1 Vivado工程目录里到底装了什么很多初学者第一次看到Vivado生成的工程目录都会被那一大堆文件夹吓到。表面上是一个 project_name.xpr 工程文件实际上旁边还跟着 project_name.runs、project_name.cache、project_name.hw、project_name.sim、project_name.ip_user_files、project_name.srcs、project_name.gen 等一大堆目录。平时打开工程、运行综合、跑仿真这些目录会被不断写入临时文件。以我手头一个中等规模的Zynq工程为例源码里的RTL文件一共也就40多个XDC约束文件2个BD文件1个总共不到600KB。但完整跑完一次综合和实现之后整个工程目录膨胀到了3.2GB。其中 .runs 目录接近2.5GB——里面全是综合、实现的 checkpoint、中间网表、报告、位流文件。.cache 和 .ip_user_files 加起来又有五六百MB都是IP核生成过程的缓存和中间文件。这些文件有一个共同特点它们全都可以通过重新执行工具流程再生成。这个特点和“源代码”有本质不同。RTL、XDC、XCI、BD这些是你自己写的或手动添加的设计输入没了就真的没了。而 .runs、.cache、.hw、.sim 这一类本质上是 Vivado 根据输入文件自动计算出来的“结果”和“过程数据”。区分好这两类就是工程瘦身的第一课。1.2 精简后真正需要保留的最小文件集合如果一个Vivado工程需要完整保留“可重建、可复现、可继续开发”的能力那最小集合其实非常小所有RTL源文件.v、.sv、.vhd约束文件.xdcIP核定义文件.xci和 Block Design 文件.bd仿真源文件如果有建议保留工程描述信息.xpr或者更好的选择TCL重建脚本其他附属文件比如自定义的 Bitstream 设置、XSIM 脚本、配置脚本把这一堆东西收集好通常也就几百KB到一两MB。如果再放进Git仓库用文本方式管理体积更可控。我做过最极端的一个纯逻辑工程所有源码加上TCL脚本压缩后只有12KB。这也是为什么网上经常有人提“Vivado工程压缩到几Kb”的原因——这里说的“几Kb”指的是工程定义脚本本身而不是整个源码目录。任何声称“整个工程只剩几KB”的文章基本都是在玩文字游戏真实的良性实践是核心脚本几KB源文件完整保留生成物一概不存。1.3 为什么不能直接靠压缩软件有人会问直接用WinRAR或者7-Zip把整个工程压成一个包不就行了能压但问题很多。第一压缩的是“过程产物”。3GB的工程压缩完可能还有1GB多因为 .runs 里有大量已经打包好的二进制数据。你把这个压缩包发给别人对方解压后打开工程Vivado往往还是会触发重新综合、重新布局布线因为工程里引用的中间文件路径变了或者版本信息对不上。换句话说你压了个寂寞。第二Git完全不友好。用Git管理工程如果直接提交整个工程目录每次跑完综合都会产生几万个变化文件diff没法看仓库体积爆炸。而TCL脚本是纯文本每次变化可能就是几行内容Git能清清楚楚显示“增加了一个源文件”、“修改了某条约束”。第三跨版本迁移难。用Vivado 2020.2建的工程换到2022.2打开.xpr 文件也得有兼容过程。但TCL脚本本身就是一套指令新版Vivado执行脚本时可以根据自己的版本规则重新建立工程兼容性反而更好。所以我一直建议团队里的同事真正要进版本管理、要交付、要归档的是“源文件TCL脚本”这个组合而不是那个巨大的工程目录。2. 核心方案落地用 write_project_tcl 把工程定义“导出”成几KB脚本2.1 先理解 write_project_tcl 做了什么Vivado 自带一个命令叫 write_project_tcl它能把当前打开的工程“翻译”成一个TCL脚本。这个脚本不是简简单单记录了一个工程名而是完整描述了整个工程的构建过程先 create_project 创建工程然后 add_files 添加所有源文件设置器件型号加载约束文件设置仿真文件添加IP关联Block Design甚至包括一些工程级属性。执行这个脚本就等于告诉Vivado按照这份“施工图纸”重新盖一栋一模一样的楼。生成脚本的本质是把一个“二进制工程状态”转译成“可读的文本指令”。这从根本上改变了工程的存储形式——二进制状态庞大、难比对、容易损坏文本指令轻量、可读、易修改。你甚至可以直接用文本编辑器改TCL脚本比如换一个FPGA型号、增加一条约束改完再执行工程就变了。我在实际项目里最常用的就是这么一行write_project_tcl ./recreate.tcl -force -no_copy_sources历史原因是因为早期Xilinx官方文档建议用 write_project_tcl 配合 copy_sources 把所有源文件拷贝到指定目录做到“全自动备份”。但对于绝大多数用Git管理源码的团队来说这没有必要。我更推荐 -no_copy_sources这样生成的脚本里只写源文件路径不复制文件脚本本身保持很小。2.2 实际操作三种生成方式任选第一种GUI操作。打开你的Vivado工程菜单栏点 File - Project - Write Tcl...在弹出的对话框里选择输出脚本路径勾选需要的选项比如“Copy sources to new location”不勾选点击确认。这种方式适合不熟悉命令行的同学生成效果和我用命令行的结果基本一致。第二种TCL Console交互命令。在Vivado底部打开 TCL Consolecd 到你想要存放脚本的目录然后执行刚才那行 write_project_tcl。注意路径的处理建议所有源文件放在工程根目录下并以相对路径方式生成脚本。我最常用的是下面这种组合cd [file dirname [get_property file_name [current_project]]] write_project_tcl ./recreate.tcl -force -no_copy_sources第一步 cd 到工程所在目录第二步生成脚本。这样生成的脚本里源文件路径就全是相对于工程根目录的路径后面移动整个文件夹、换机器都不会有路径问题。没有第一步的话脚本里很容易出现绝对路径到别人电脑上就废了。第三种批处理模式。不开图形界面直接用命令行vivado -mode batch -source write_recreate.tcl其中 write_recreate.tcl 里写的就是前面那两行命令。这种方式适合自动化流程比如在CI服务器上每天晚上自动生成一次脚本并提交到Git。2.3 生成的TCL脚本里长什么样生成出来的 recreate.tcl 本质上是一个文本文件但打开它你会发现它比想象中规整。它的大致结构是# 创建工程指定器件和工程名 create_project project_1 ./project_1 -part xc7z020clg400-1 # 添加源文件 add_files -norecurse {./src/top.v ./src/axi_wrapper.v} add_files -norecurse {./src/constraints/top.xdc} # 设置顶层文件 set_property top top [current_fileset] # 添加IP核 add_files -norecurse {./ip/clk_gen/clk_gen.xci} update_compile_order -fileset sources_1 # 添加仿真文件 add_files -fileset sim_1 -norecurse {./sim/tb_top.v} # 关闭工程 close_project实际脚本会比这个复杂尤其是工程里如果设置了局部属性、VHDL库名、多个约束集、自定义的Implementation策略时对应内容都会自动生成。核心价值在于它把这个工程里所有“非生成物”的信息都压缩成了几百行文本。我见过最复杂的工程脚本也不过3000多行而工程目录仍然可以小到几KB到几十KB不等。这里顺便提一个容易忽略的细节生成的脚本里如果包含了IP核文件执行脚本后Vivado会自动把这些IP加入工程并触发IP的重新生成流程。所以脚本还原出的工程在初次打开时可能会提示“IP需要重新生成”这属于正常现象不是脚本有问题。3. 从几KB脚本还原完整Vivado工程两种实践路径3.1 手工还原GUI执行 source拿到 recreate.tcl 和完整源码目录之后第一步是先确保目录结构没有乱。我的习惯是保持如下布局project_root/ │ ├── recreate.tcl ├── src/ # 所有RTL、XDC、IP、BD等源文件 ├── sim/ # 仿真源文件可选 └── doc/ # 设计文档可选目录定好之后打开Vivado在 TCL Console 里先 cd 到脚本所在目录直接执行cd [file dirname [get_property file_name [current_project]]]等一下如果你当前没有打开任何工程这个 current_project 取不到值。更简单的方式是直接用完整路径cd D:/work/project_root source ./recreate.tcl执行 source 之后Vivado开始按照脚本一步步创建工程、添加文件、配置属性。正常情况下几秒到几十秒就能创建一个新的工程文件。之后你可以像平时一样打开新生成的 .xpr 文件继续综合、实现、生成比特流。不过需要提醒的是这种方式在 GUI 里执行TCL Console 会输出大量过程信息。如果脚本中途因为某个文件找不到报错后面的命令就不会执行。解决办法是检查报错提示中的路径名调整目录结构或者用文本编辑器打开脚本修改对应的 add_files 行。我一般会先在改完的路径下建一个最简单的Vivado工程确认文件路径书写方式没错再执行大脚本。3.2 命令行全自动还原适合脚本化和CI如果在服务器上还原工程或者想把这步写进自动化流程推荐用批处理模式。创建一个 source_recreate.tcl 文件内容只要一行source /absolute/path/to/recreate.tcl然后在命令行执行vivado -mode batch -source source_recreate.tclVivado 会在 batch 模式下逐个执行脚本命令执行完毕自动退出。这种方式不打开GUI、不吃显卡资源、运行速度快非常适合做持续集成。我在公司内部就是用这种方式完成“拉最新代码 - 重建工程 - 跑综合 - 出报告”的每日构建流程。如果你还需要在还原工程后立刻进行综合、生成比特流可以在 source_recreate.tcl 里追加命令source /absolute/path/to/recreate.tcl open_project ./project_1/project_1.xpr launch_runs impl_1 -to_step write_bitstream -jobs 8 wait_on_run impl_1wait_on_run 会让批处理一直等待实现跑完这样脚本结束后直接在目标目录里找 .bit 文件即可。整个过程全自动很适合做夜间回归。3.3 还原后必须做的检查清单脚本成功执行不代表万事大吉我每次还原工程后都会迅速检查几项检查工程器件型号是不是预期型号。如果脚本里写了 -part xc7z020clg400-1而新环境选型默认是别的型号工程可能创建失败或警告。打开生成的 .xpr 确认 device 和 package。检查源文件是否都被正确添加。在GUI中进入 Sources 面板对比原工程的文件列表确认有没有漏文件。特别是那些放在工程外部的源文件脚本里如果写的是绝对路径换个目录就找不到了。检查约束文件是否生效。综合前先跑一次 report_utilization确认时序约束有没有真正加载。有时脚本会因为某种原因丢掉了 defines 或 xdc 的优先级设置导致布局布线结果差异很大。检查IP状态。如果工程里有XCI文件还原后IP可能处于“需要升级”或“output products 缺失”的状态。在TCL Console里运行get_ips report_ip_status如果有需要升级的IP右键或通过 TCL 命令执行升级。这一步省略的话后续综合时大概率会报错。这些检查实际上花不了两分钟但能避免后面在综合、实现阶段才暴露一堆低级错误。经验之谈还原工程之后先不要急着跑大任务先做一次快速综合语法检查这类问题都能提前暴露。4. 常见问题与排查TCL脚本还原踩坑实录4.1 路径问题导致源文件找不到这是最常遇到也最好解决的问题。还原新工程时报错信息通常是这样的ERROR: [file 6-3] File ./src/top.v cannot be opened for reading.原因无非就是脚本里写的相对路径和你实际的目录结构不一致。解决方案也简单要么把源码目录调整到脚本期望的路径要么用文本编辑器全局替换脚本里的前缀路径。这里有一个经验如果你是拷贝别人工程拿到的脚本先打开脚本看看 add_files 的路径是什么风格。Windows下默认用反斜杠Linux的Vivado可能处理不了如果脚本里用了D:/work/...这种绝对路径拷贝到其他目录后会直接失效。为了避免这类问题我一直坚持生成脚本时先 cd 到工程根目录然后使用相对路径。4.2 IP核和Block Design的版本兼容问题用TCL脚本还原工程后经常会看到IP处于 Locked 状态或版本不是最新。这个在跨版本、跨机器的场景下尤其常见。Vivado 2020.2 生成的IP核用2022.2打开大概率会出现兼容性警告。处理的第一步不是盲目点击“Upgrade IP”而是先检查 IP 的版本变化范围。右键IP核选择“Report IP Status”确认哪些IP不可用、哪些IP需要重新生成。升级IP时注意查看它的端口和参数是否发生变化——如果整个工程只有一个自动化生成的时钟IP基本可以放心让它重新生成但如果你在RTL里手动例化了IP的原始端口名升级后接口变了编译会立刻报错。Block Design也有类似行为。.bd 文件本质上是一个文本描述还原工程后重新 open_bd_designVivado会重建整个模块图。只要文件本身没损坏一般都能恢复。4.3 综合策略和增量编译参数丢失write_project_tcl 生成的脚本包含了很多工程属性但并不是百分之百覆盖所有内部状态。比如自定义的 Implementation Strategy、增量综合选项、约束文件集合的 target 配置有时候并不能完美还原。我自己踩过一个坑原工程里设置了“增量编译”模式用的是上一次布局布线的 checkpoint但还原后的新工程没有这个 checkpoint 文件导致启动综合时直接报错找不到 DCP。后来我做瘦身归档时会额外把最终的实现 checkpoint比如 .runs/impl_1/top_route_design.dcp和比特流保留在archive目录里作为可选项而不是必须依赖项。这样既不拖累工程体积又能给需要马上出板的同事一个直接可用的文件。4.4 常见问题速查表问题现象可能原因解决办法脚本执行时提示找不到源文件相对路径与目录结构不匹配检查脚本中的前缀路径调整源码目录或全局替换路径打开还原工程后IP锁定不可用IP核版本跨版本或output products缺失在IP Catalog中执行IP Status按提示重新生成综合时报错找不到约束集合XDC未正确关联到constrs文件集用 set_property used_in_synthesis false/true 重新设置约束还原后顶层module不是预期模块脚本中的 set_property top 设置错误重新 property 设置顶层文件生成比特流失败但综合实现正常可能缺失debug核或约束条件检查是否添加了ILA核的XDC约束必要时重新配置ILA运行批处理时无图形化反馈光标长时间不动综合任务耗时长batch模式无进度条使用 -log 参数重定向日志实时查看运行进度脚本放在中文路径下执行报错Vivado对中文路径兼容性较差一律使用英文路径归档目录也避免中文这张表不能覆盖所有问题但列出的都是我在实际交付和迁移过程中遇到过的高频问题。真到排查的时候第一原则还是看日志Vivado的每条报错都会带一个错误代码和上下文信息别急着问群先自己 trace 一遍。5. 工程大瘦身的进阶玩法从手工压缩到自动化工作流5.1 用Git管理Vivado工程ignore文件是关键前四节讲的更多是一次性的“压缩和还原”但如果你真正想从工程体积的泥潭里走出来光靠手工执行 write_project_tcl 还不够要把它变成一个持续性的工作流。第一步就是让Git好好管住工程。Git本身并不适合直接管理整个Vivado工程目录因为它会追踪 .runs 里的几万个中间文件。所以做法是把源码和TCL脚本纳入Git把生成物全部 ignore。一份比较稳妥的 .gitignore 长这样# Vivado生成文件 *.runs/ *.cache/ *.hw/ *.sim/ *.ip_user_files/ *.gen/ *.jou *.log *.str *.backup *.dcp *.bit* *.bin *.ltx *.bmm # 工程文件TCL脚本才是标准 *.xpr这里有个争议点.xpr要不要忽略。我的建议是忽略它。因为既然 recreate.tcl 就是工程的“施工图纸”每次临时创建的 .xpr 只是图纸的渲染结果没必要进版本管理。真需要看哪个版本对应哪个工程配置用TCL脚本的Git历史就足够了。5.2 一键清理脚本把工程目录打回轻量状态日常开发中我经常要在工程目录里来回切换、打patch、做回归。每次手动删 .runs、.cache 太累于是写了一个简单的批处理脚本放在工程根目录下。Windows 下新建 clean_vivado.batecho off echo Cleaning Vivado generated directories... for /d %%i in (*.runs *.cache *.hw *.sim *.ip_user_files *.gen) do ( if exist %%i rmdir /s /q %%i ) echo Cleanup done.Linux/macOS 下用 clean_vivado.sh#!/bin/bash echo Cleaning Vivado generated directories... rm -rf ./*.runs ./*.cache ./*.hw ./*.sim ./*.ip_user_files ./*.gen echo Cleanup done.执行完这个脚本后工程目录通常只剩 .srcs、TCL脚本、以及刚生成的 .xpr。整个体量马上降到几百KB。之后再用 write_project_tcl 生成一次脚本目标工程就算完成了一次“快照”。这里顺便提一个细节清理之后不要直接重新打开 .xpr 然后跳过所有提示继续跑。因为旧的综合结果已经被删掉重新打开工程会提示“工程状态已过期”这其实是正常的。直接 launch_runs 综合实现即可。5.3 进阶把TCL脚本嵌入CI/CD流程当团队规模超过两三个人、设计任务越来越重的时候手工跑TCL脚本也会成为瓶颈。更合理的做法是让服务器每天自动完成“拉取最新代码 - 清理旧工程 - 用TCL脚本重建工程 - 完整跑一遍综合实现 - 输出报告”这个闭环。我之前在团队里搭过一个最简单的自动化流程大致框架是在GitLab Runner上安装Vivado写一个 pipeline job构建脚本的核心就是这么几行git pull origin master vivado -mode batch -source ara/source_recreate.tcl vivado -mode batch -source ara/build_bitstream.tcl其中 source_recreate.tcl 就是前面讲的还原脚本build_bitstream.tcl 则负责打开工程、启动综合实现、生成比特流。整个流程跑完把 .bit 文件和时序报告作为 artifact 保存。这样每天早晨到公司只需打开流水线页面看一眼回归结果根本不需要在自己的笔记本上手动跑Vivado。对于小团队或者个人项目直接用 Windows 任务计划程序或者 Linux 的 cron 定期执行也同样可行。核心思想只有一个让“工程重建”这个行为变成命令而不是操作GUI的一连串手动点击。5.4 我的个人习惯最后分享一个我自己坚持了很久的小习惯每完成一个功能阶段我就会在工程根目录执行一次 write_project_tcl 生成带日期后缀的快照脚本放到 archive/ 目录里。比如recreate_top_v1_2_20250315.tcl。配合Git对源码的版本管理意味着任何时间点的设计状态都能在几分钟内被完整还原出来。这个习惯看起来很朴素但让我避免了无数次灾难。印象最深的一次是笔记本硬盘坏掉当时所有本地工程文件全部丢失但好在Git仓库里有最新源码NAS上有上一版TCL脚本。换新机器后装好Vivado拉代码source一下快照脚本不到三分钟就回到了之前的开发状态。那一刻你会深刻体会到工程再大也大不过一份设计图纸Vivado工程瘦身瘦到底省下的不只是硬盘空间更是你重新找回设计状态的时间。