1. 这个问题是怎么冒出来的先说说我自己的经历。上个月我做完一个带千兆网口和DDR3的工程综合实现跑完、板上也验证过一轮想把这套逻辑复制一份当模板给另一个项目复用。我直接在文件管理器里把整个工程文件夹选中、复制、粘贴改了新名字然后双击新目录下的 .xpr 打开。Vivado 界面倒是正常弹出来了工程结构看着也完好可我刚要点 Run Synthesis进度条还没走两步底部 Console 就甩出一行红字[Common 17-1294] Unable to create directory C:/Users/xxx/Desktop/project_copy/project_copy.runs/synth_1我当时的第一反应是目录不是就在那儿吗我复制的时候明明是整目录拷贝怎么可能创建不了目录。于是打开资源管理器去确认发现project_copy.runs这个文件夹确实存在但里面只有一个空的synth_1子目录而原工程里的synth_1下本来应该有一堆runme.log、.Xil、缓存文件。最诡异的是我再仔细看连synth_1这个文件夹都只有一层壳里面什么都没有。这就是典型的“工程复制后目录状态与工程配置不一致”引发的连锁反应。Xilinx 在报这个Common 17-1294错误时通常不会只报一次它会先报创建目录失败紧接着往往还会跟一串类似ERROR: [Common 17-170]的路径解析失败或者干脆直接中断综合流程。要理解为什么复制个工程都能整出这么多事得先搞清楚 Vivado 在启动综合时对目录做了什么。1.1 报错文本拆开看[Common 17-1294]这条错误本身的意思非常直白Vivado 尝试在指定路径创建目录但失败了。失败原因通常有三类路径对应的父目录不存在而且 Vivado 没有自动创建父目录的权限。路径指向的位置是一个已存在的文件而不是目录导致同名冲突。Vivado 进程对目标磁盘分区没有写入权限。但放到“工程复制”这个具体场景里情况更复杂。因为当你用操作系统自带的复制粘贴功能拷贝整个 Vivado 工程目录时Windows 不会百分百保证每个隐藏文件、每个目录属性、每一条路径关联都原样搬过去。尤其当原工程的runs目录下已经有上一次综合生成的中间文件时复制出来的副本很容易出现“目录层级稀疏”的情况——表面上文件夹都在但内部结构被截断了。Vivado 一运行synth_1子流程发现需要的目录层级不完整就会尝试自行创建结果因为种种原因创建失败于是报出Unable to create directory。1.2 这个错误的“高发人群”我后来在几个 FPGA 技术交流群里问了问发现踩到同一个坑的人还挺多基本集中在几个场景拿别人的工程直接用压缩包解压后路径变了。自己用“复制粘贴”大法复制整个工程像Copy一个 Word 文档那样随意。把工程放在网盘同步目录、U盘、移动硬盘上复制过程中文件状态不稳定。工程路径里带了中文、空格、括号等特殊字符复制后路径解析出现偏差。如果你是这几类用户那这篇内容值得看完后面的排查步骤都是我实打实验证过的。2. 排查思路不要上来就重装软件很多朋友一看到 Vivado 报错第一反应是“坏了软件不行了”然后开始重装、换版本、装驱动折腾一整天。我踩过这种坑负责任地告诉各位Common 17-1294这类错误极少是软件安装本身的问题绝大多数是工程文件状态和路径环境的问题。重装Vivado不仅浪费时间而且大概率解决不了。正确的排查顺序应该是检查工程路径本身是否合法。检查目标目录的实际状态。检查 Vivado 进程对目录的权限。检查复制过程中是否丢失或损坏了工程元数据。如果以上都没问题再考虑用 Vivado 自带的归档/导出功能重新生成工程。下面我按照这个顺序把每一步的具体操作和判断标准讲清楚。2.1 第一步先确认路径符不符合 Vivado 的“脾气”Vivado 对工程路径相当挑剔。根据 Xilinx UG892 的说明工程路径中不能包含中文字符、不能有空格、不能以数字开头在某些版本中路径总长度也有隐性限制。很多人复制工程时图省事直接把文件夹命名为工程副本_final_v2或者my project copy这种路径在 Windows 资源管理器里看着没问题但 Vivado 内部用的是 Tcl 脚本解析路径空格和中文很容易在拼接命令时炸掉。我之前遇到过一个案例朋友把一个工程放在D:\My Projects\uart demo\目录下复制后工程一综合就报Common 17-1294。我把路径里的空格去掉改成D:\Projects\uart_demo\再重新打开问题直接消失。所以遇到这个报错先别急着改工程内容第一件事是把工程放到一个纯英文、无空格的短路径下试试。打个比方Vivado 的路径解析就像一个只认标准普通话的语音助手你用方言跟它说话它听不太懂但也不会明说最后就憋出一个莫名其妙的错误。路径里有空格和中文就是这个“方言”的典型代表。2.2 第二步检查复制的工程目录里有没有“半截货”我在文章开头说的那个情况——synth_1文件夹只有一层空壳——其实非常有代表性。用 Windows 的资源管理器复制粘贴大目录时如果目录层级很深、文件很多偶尔就会出现“复制”操作提前结束但系统没有报错的情况。尤其是当源目录里正有别的程序在写文件或者杀毒软件正在扫描时复制出来的副本很可能缺文件。判断方法很简单对比原工程和复制工程的runs目录、.srcs目录的大小和文件数量。在 Windows 下可以右键属性看“大小”和“包含文件数”。如果复制出来的目录文件数明显少于源目录那这个复制就是不可靠的别再在这个副本上浪费时间排查了重新复制一遍或者干脆走 Vivado 官方的导出流程。2.3 第三步看报错目录是否真实存在如果你已经确定路径是干净的了那就要去文件系统里实地检查。在 Vivado 报错提示的那个路径上打开资源管理器一层层点进去看注意两件事路径上的每一级目录是否存在。目标目录是不是被一个同名文件占用了。第二点很容易被忽略。我见过有人工程目录下有一个文件叫synth_1没有扩展名同时还需要创建一个同名目录Windows 不允许文件和目录同名Vivado 也就跟着报Unable to create directory。这种文件通常是不小心的历史遗留删掉就行。还有一个冷门情况目标路径的某级父目录其实是个“快捷方式”或者“软链接”Symlink。Vivado 在某些版本中对软链接处理得不好可能在解析真实路径时失败。如果检查发现目录实际是快捷方式建议把真实目录直接搬过来。2.4 第四步考虑读写权限问题这一步在 Linux 环境下尤其重要Windows 下相对少一些但也不是没有。Vivado 运行综合和实现时会在工程目录下创建.runs、.cache、.hw等文件夹同时往里面写入日志、检查点、网表等大量中间文件。如果工程所在目录被设置为只读或者当前用户对该目录没有“完全控制”权限Vivado 就会在创建目录或写入文件时失败。在 Windows 上检查权限右键工程根目录选“属性”。切到“安全”页签看当前用户是否有“修改”和“写入”权限。如果没有点“编辑”添加权限。如果怕麻烦可以直接把整个工程目录的只读属性去掉。在 Linux 上就简单了chmod -R urwx /path/to/project做了这个操作之后再重新打开工程跑综合大概率能过。3. 解决过程的完整实录理论讲了一堆我把我那个工程从报错到恢复的全过程按时间线写出来你可以对照着抄作业。3.1 第一次尝试新建同名目录手动“补位”最开始我看到Unable to create directory ... synth_1想走捷径你 Vivado 不是创建不了目录吗那我手动给你建好不就完了。于是我在资源管理器里进了project_copy.runs右键新建文件夹起名synth_1然后满怀期待地再次点击 Run Synthesis。结果呢报错变了从Common 17-1294变成了ERROR: [Common 17-170] Unable to open file C:/.../project_copy.runs/synth_1/.Xil/Vivado-xxxxx/_xocc_compile_...也就是说目录虽然是有了但 Vivado 在综合过程中还需要往里面写更多的临时子目录和小文件比如.Xil缓存目录、runme.sh脚本等仅仅建一个空壳目录根本不够。Vivado 是按一套固定流程去生成整个目录树的少了任何一层它都会继续尝试创建而创建失败的根因并没有被“手动补位”解决。这次尝试让我明白了一件事症状在“创建目录”但病因是“复制过程产生的目录树损坏”手动补一个文件夹是在治标不是治本。3.2 第二次尝试重置工程运行状态抱着“可能只是中间状态乱了”的想法我用之前做过的一个操作——在 Vivado 的 Tcl Console 里执行reset_run synth_1这个命令会把指定的综合运行配置重置删除.runs/synth_1下的生成文件把运行状态恢复为“未运行”。理论上如果只是运行状态记录和实际目录不一致重置后问题应该消失。但结果依然不行。Console 里先打印了一行WARNING: [Vivado 12-507] No runs in the project之类的话然后我再启动综合时老错误原封不动地回来了。这说明工程元数据里记录的运行信息本身可能就有问题不是单纯的重置能解决的。到这里我开始意识到这个复制工程除了目录树有问题可能连.xpr工程文件内部记录的路径、运行配置都已经和外部文件系统对不上了。继续在原副本上修补成本会越来越高。3.3 关键转折用 Vivado 的 Tcl 命令干净地重建工程后来我想通了与其在坏副本上修修补补不如回到“源工程”这个一切正常的基准点用 Vivado 自己的导出/导入机制来生成一份干净副本。这才是治本的做法。具体命令如下。在源工程已打开的前提下在 Tcl Console 里执行# 关闭当前工程 close_project # 以只写模式打开目标工程路径自定义但要保证无中文无空格 open_project C:/Work/template_uart/template_uart.xpr # 将当前工程归档到一个压缩包 archive_project -include_runs -include_generated_files C:/Work/template_uart_archive.zip执行完archive_project后Vivado 会把你当前工程的所有源文件、约束文件、IP配置、运行配置连同必要的中间生成文件全部打包进一个 zip。这个压缩包是自包含的、干净的、路径无关的。然后我在资源管理器里新建一个目录比如C:/Work/new_project/把刚才的 zip 解压进去打开解压后的.xpr再跑一遍综合。这次问题彻底消失了。这里想补充一下archive_project的几个参数含义-include_runs把已有的综合/实现运行配置一起打包方便新工程直接接着跑。-include_generated_files把 IP 生成的文件也打进去避免在新机器上重新生成 IP 时出现兼容性或者网络下载问题。如果不加参数默认只归档源文件IP 和运行配置会在新工程中重新生成。3.4 为什么“归档解压”能根治问题因为archive_project是 Vivado 自己生成的压缩包里面的路径引用是经过内部归一化处理的不会像操作系统的复制粘贴那样把一个深层目录结构搬得七零八落。更关键的是归档包重新解压后工程文件和文件系统之间的对应关系是由 Vivado 自己生成的runs目录、sources目录的层级关系完全符合 Vivado 内部的预期。这就像是你请搬家公司和自己在凌晨搬家的区别。自己搬家具可能少几件、装错了箱子搬家公司按清单打包到了新家按清单归位虽然贵一点但心里有底。3.5 如果源工程也打不开怎么办如果手头连一个状态完好的源工程都没有或者源工程本身就是从别人那里复制来的那也别慌。还有一种更基础的修复路径用记事本打开.xpr文件检查里面的Project标签下的Version、Part等信息是否完整。如果.xpr文件本身损坏严重可以新建一个空工程选同一块 FPGA 型号然后通过Add Sources手动把.v、.vhd、.xdc文件加进去。对于 IP建议直接用 IP Catalog 重新生成虽然费点时间但比抱着一个可能损坏的 IP 副本硬啃要好得多。这个方法其实就是“放弃治疗重新接骨”。对于代码源文件完好、但工程元数据损坏的情况往往是最快的出路。4. 复制工程前应该做什么一套靠谱的规范化流程踩过这个坑之后我现在复制任何 Vivado 工程都不再直接去文件管理器里 CtrlC、CtrlV 了。步骤如下照着做基本不会再碰到Common 17-12944.1 先清掉工程里的“运行垃圾”复制工程前先打开 Vivado打开要拷贝的工程然后在 Tcl Console 里执行# 删除综合运行的生成文件 reset_run synth_1 # 删除实现运行的生成文件 reset_run impl_1如果工程时间比较久了里面可能残留很多.cache、.runs下的硬编译产物这些文件不仅体积巨大而且容易在复制时引发权限和目录问题。你也可以手动在资源管理器里把工程目录下的.runs目录.cache目录.hw目录.gen目录.Xil目录这是隐藏目录Windows 下要开“显示隐藏项目”才看得到整个删掉然后关闭工程。这样剩下的就是一份纯源代码、约束、IP定义和工程配置体积小、结构简单复制时几乎不会出问题。我用一个表格总结一下哪些文件建议保留、哪些建议删除项目建议原因.srcs目录保留源代码、约束都在这里核心资产.xpr文件保留工程入口.runs目录删除综合/实现的中间产物占用空间大.cache目录删除缓存文件可重新生成.hw目录删除硬件相关临时文件.gen目录删除IP 生成缓存.Xil目录隐藏删除调试缓存经过这一轮“瘦身”后工程目录会清爽很多复制速度和成功率都会大幅提高。4.2 复制后立即执行的“三查”复制完成并打开新工程后不要急着点 Run Synthesis先按下面三个步骤快速体检查看Sources窗口里的文件图标看是否有文件前出现黄色的感叹号。出现感叹号说明文件路径缺失需要右键Refresh或者重新添加。打开Project Settings - Synthesis确认 Top Module 名字没有变红、没有变成 Unknown。在 Tcl Console 里执行get_property DIRECTORY [get_projects]检查返回的路径是不是新工程的实际路径而不是老的源工程路径。如果路径还是老的需要在Project Settings - General里手动改一下工程目录。这个“三查”流程能帮你把大部分复制后遗症提前暴露出来避免在综合时报错后才手忙脚乱。4.3 直接用 Vivado 的“Project Manager”归档功能如果你实在记不住 Tcl 命令没关系GUI 路径也可以打开工程点击菜单栏File - Project - Archive。在弹出的对话框中勾选Include runs和Include generated files如果新工程里不想保留中间结果也可以不勾。设置归档 zip 的保存路径点确定。归档完成后把 zip 发到任何一台机器上解压打开就行这套流程和 Tcl 命令效果完全一样只是多了个图形界面。5. 常见问题与排查技巧实录5.1 问题速查表报错信息可能原因处理方式Common 17-1294 Unable to create directory复制导致目录树损坏/权限不足/路径非法优先检查路径和权限必要时使用archive_project重新导出Common 17-170 Unable to open file目录存在但文件缺失或占用删除对应运行目录重新运行黄色感叹号文件丢失.srcs下源文件路径被改右键文件Refresh或重新 Add SourcesERROR: [Project 1-481] No part selected工程元数据损坏打开工程设置重新选器件型号综合能过但实现报错routed property missing运行状态记录被破坏执行reset_run impl_1后重新跑5.2 一个 Linux 下的特殊案例我有一个做嵌入式方向的朋友在 Ubuntu 下用 Vivado 2022.2把工程复制到另一台机器后同样报了Common 17-1294。排查到最后发现是复制时用了cp -r但源工程里有个软链接目录指向了/home/user/old_project/runs复制后那个软链接在新机器上指向了一个不存在的路径Vivado 一尝试通过软链接创建子目录就直接失败。解决方法是复制前先把软链接替换成实际目录的硬拷贝或者在复制时使用cp -rL这个参数让cp把链接目标的内容也复制过来而不仅仅是复制一个指向旧路径的链接。这个案例提醒我一点Linux 下复制工程cp参数的选择很关键。默认的cp -r复制软链接时只复制链接本身不复制目标内容这在普通文件场景下问题不大但碰到 Vivado 这种高度依赖绝对路径解析的工具就是实打实的坑。5.3 如何从报错路径反推工程“秘密”Vivado 报错信息里的路径其实很有信息量。当你在 Console 里看到[Common 17-1294] Unable to create directory C:/Users/xxx/Desktop/project_copy/project_copy.runs/synth_1注意看project_copy/project_copy.runs这段。正常工程里runs目录应该是工程目录的子目录格式通常是工程名.runs。如果你的工程目录叫project_copy那运行目录就是project_copy.runs。但当路径里出现project_copy/project_copy.runs说明复制后的目录嵌套结构发生了变化很可能你复制的时候把整个项目文件夹放入了另一个同名文件夹里比如原工程在A文件夹你又把A整个拖进了B导致工程实际路径比.xpr文件里记录的路径多了一层。这种情况下最简单的修复方法不是改.xpr而是把工程的物理路径调整成和.xpr内部记录的一致。说白了就是要么移动文件夹要么用archive_project重新生成一份对齐的工程文件。5.4 关于杀毒软件和网盘的全员警告我后来复盘自己第一次踩坑的经过怀疑还有一个潜在帮凶杀毒软件实时防护。Windows Defender 扫描大目录时会对每一个新建文件做一次实时的“行为检查”在这个检查过程中文件可能处于“半锁定”状态。如果此时 Vivado 尝试在同一个目录里创建子目录系统可能返回一个“权限不足”的假信号Vivado 就误报为Unable to create directory。此外如果你把工程放在 OneDrive、坚果云这类网盘同步目录下网盘客户端的大文件同步也可能导致类似问题。复制出来的工程还没等本地完全落盘就被网盘客户端“接管”上传了导致 Vivado 读取时文件状态不稳定。建议是Vivado 工程这种大型、多文件、高频率读写的项目老老实实放在本地磁盘的一个固定目录下不要放到网盘同步目录或U盘上。这不是保守是省时间。工程同步可以等关闭 Vivado 之后手动做。6. 最后的几点心得把Common 17-1294这个错误从头到尾解决完我最大的感触是很多 Vivado 工程迁移问题根本不是工具链本身的问题而是我们对“工程文件的结构”缺乏足够的敬畏。Vivado 的工程不像 Word 文档是一个单独文件它是一个由几十个甚至上百个文件夹、配置文件、缓存目录组成的复合体。用复制普通文档的方式去复制它出问题只是概率问题不出问题才是运气好。现在我自己处理工程复制的固定套路是先在 Vivado 里reset_run清干净中间产物然后用archive_project打包再到新目录解压。整个过程多花不到三分钟但能省下好几个小时排查错误的时间。如果你手头正好也被Common 17-1294卡住了先冷静下来按我上面说的顺序检查一遍路径、权限、目录状态、归档导出。大概有九成以上的概率能直接解决。剩下那一成多半是工程文件本身已经损坏到无法修复了那就老老实实新建工程重新添加源文件吧。