在Dify里做工作流编排，很多朋友应该都撞到过同一个限制：变量引用只能引用一层。刚遇到时我以为是配置写错了，反复检查节点连接、变量命名、拼写和画布顺序，后来才发现这是平台在变量作用域上的固定规则。它不是配置失误，也不是BUG，而是Dify为了让依赖关系清晰、运行结果可控，刻意收窄了变量的可见范围。

这篇文章从我自己实际踩坑的过程出发，把“只能引用一层”拆开揉碎讲清楚：它到底卡在哪、平台为什么要这样做、以及有哪些绕过套路可以直接抄作业。如果你正被变量引用问题折磨，这篇应该能帮你省下不少排查时间。

1. Dify的变量可见范围：为什么节点之间不是全局互通

1.1 每个节点都有自己的“输出信封”

Dify画布上的每个节点执行完，都会产出一个结构化输出。比如开始节点输出用户填写的表单字段，HTTP请求节点输出响应状态与响应体，LLM节点输出生成的文本。节点之间通过连线建立依赖关系，下游节点能引用哪些变量，基本取决于上游链路给它递了什么。

但很多人忽略了一个关键点：这个引用关系是收敛的，不是全局的。你不能在任意位置引用任意节点的输出。实际可用的变量范围，取决于当前节点处于工作流的哪一层作用域。我经常跟朋友打比方：这就像每个节点是个小函数，你只能使用函数入参和函数内部自己产生的结果，不能越过函数边界去摸全局变量。

当你的流程里出现分支、迭代、子工作流这类结构时，作用域的收敛会更加明显。节点A分支里产生的变量，节点B分支往往引用不到；迭代内部的子节点，通常也看不到迭代外部的兄弟节点输出。这些都属于“单层引用”的表现。

1.2 两种“只引用一层”的具体表现

结合这个标题，我在项目里遇到的“只能引用一层”主要集中在两种情况。

第一种是字段层级上的限制。Dify的变量引用语法基本是{{#节点ID.字段名#}}，比如{{#http_request.body#}}、{{#llm.text#}}。这种写法只能点到节点输出的一层字段。如果上游节点返回的是一个嵌套对象或数组，你在后续节点的模板里想继续往下点，比如{{#http_request.body.user.addr#}}，变量选择器往往只能选到body这一层，再往下就选不到了。

第二种是作用域层级上的限制。当工作流存在嵌套结构时，比如迭代节点内部再挂LLM节点，或者把工作流封装成子工作流被其他流程调用，内层节点默认只能引用当前一级作用域内的变量。迭代节点内部的子节点，通常能访问的就是开始节点变量、迭代节点的输入变量、当前迭代项item，以及系统变量；迭代节点外部的兄弟节点输出，对内部节点不可见。子工作流也一样，入口收什么参数，内部就只能用什么参数，父流程的中间变量不会自动透传进去。

很多人恰恰是把这两种情况混在一起排查，才觉得Dify变量引用“完全无法预判”。先分清你卡的是字段下钻还是作用域隔离，后面处理起来会快很多。

1.3 一张表看清各位置的变量可见范围

这张表是我自己整理的简化模型，实际项目里还会有分支节点、并行节点等场景，但原理一样：你处在哪个作用域，就只看得到这个作用域允许暴露给它的变量。这个限制确实会带来学习成本，但搞懂之后，很多报错和变量缺失问题就能一眼定位。

2. 迭代节点内引用不到外侧节点：一次客服分诊流程的完整排障

2.1 当时的工作流结构

我前段时间做一个客服工单自动分诊工作流，结构大致是这样：开始节点接收工单标题、描述、客户等级、渠道来源；接着一个知识库检索节点根据工单描述检索相关文档；再往下是判断VIP客户的分支节点；最后用一个迭代节点遍历工单里的多个问题项，每个问题项都要让LLM生成一段处理建议。

流程链路是：开始节点 → 知识库检索 → 分支判断 → 迭代节点（内部挂LLM节点）。我期望内部LLM节点生成建议时，同时参考开始节点的客户等级、知识库检索返回的参考知识，以及当前迭代项的内容。这在产品直觉上非常合理：我要把“全局上下文”和“单条数据”拼接在一起。

2.2 完整的排查链路

配置内部LLM节点提示词时，我在变量选择器里翻来翻去，发现能选的只有几类：开始节点的字段、迭代节点的input、当前迭代项item。知识库检索节点的输出、分支节点的判断结果，全部不在列表里。

我第一反应是连线问题。退出去检查了一遍，知识库检索节点明明白白连接到了迭代节点的输入端口，迭代的数据源就是它的输出，链路是通的。那为什么内部节点看不到？

接下来我尝试在提示词模板里手动写下{{#knowledge_search.summary#}}，运行后工作流日志直接提示该变量不可用，不在当前节点的上游依赖范围内。这一步把问题彻底暴露了：不是节点输出不存在，而是内部节点根本没有权限引用它。

最后我查了平台说明和社区讨论，才确认迭代节点是一个独立的作用域边界。迭代节点本身能引用上游节点，因为它处在顶层作用域；但它内部的子节点被单独封装进一个子作用域，这个子作用域对外只开几个口：开始节点变量、input和item。想让内部节点使用外部变量，唯一办法是把这些外部变量显式放进input对应的数据结构里，让每个迭代元素自带完整上下文。

2.3 把外部变量“压进”每个迭代元素

理清原因后，修复方案就很直接了：在迭代节点之前加一个代码节点做数据预处理，把知识库检索结果、客户等级、渠道来源这些外部信息，合并到每个待迭代的对象里面。这样迭代内部LLM节点只从item这一个入口，就能拿到所有需要的数据。

代码大致长这样：

def main(item_list: list, knowledge: str, customer_level: str, channel: str) -> dict: enriched = [] for item in item_list: enriched.append({ **item, "reference_knowledge": knowledge, "customer_level": customer_level, "channel": channel }) return {"enriched_list": enriched}

从迭代节点开始，数据源从原来的itemList改成enriched_list，内部LLM节点引用item.reference_knowledge、item.customer_level和item.channel就能正常出结果。

改完之后整个流程跑通。后来复盘时我总结出一个规律：凡是遇到“迭代内部看不到外层”的问题，别急着找平台要全局变量，最快的方式永远是考虑能不能在上游把上下文拍平到数据里。数据自带上下文，比任何跨作用域引用都稳妥。

2.4 为什么迭代内部要设这道墙

很多人觉得这是平台偷懒，其实不是。迭代节点执行方式跟普通节点不一样，它本质上是对同一份子逻辑做多次执行。如果内部节点允许任意引用外层动态变量，多次执行时就会出现变量竞争：一次执行读到旧值、另一次读到新值，运行结果和画布上看到的依赖完全对不上，调试会变成灾难。

把作用域收敛到input和item，相当于平台强制保证：每次迭代的运行环境只依赖“输入数据集 + 当前元素 + 固定的全局变量”，执行结果天然可预测。这比看似方便实际不可控的全局引用要可靠得多。

3. 复杂对象下钻失败：模板里点不进去的深层字段

3.1 典型场景：外部API返回嵌套结构

第二个高频坑是字段层级上的单层限制，通常出现在接外部系统时。有一次项目里，一个代码节点调用外部接口后返回了这样的结构：

{ "company": { "name": "示例企业A", "address": { "province": "某省", "city": "某市" } } }

我在后续LLM节点的提示词模板里，想直接写“公司名是{{#code.company.name#}}，城市是{{#code.company.address.city#}}”。结果打开变量选择器，能选的只有code.company这一层；选中后在模板里展示的就是{{#code.company#}}，再往后无论怎么点都没反应。手动补上子字段后，运行取到的是空值或不可用内容。

这个现象就是典型的“只能引用一层”：在变量选择器层，Dify只解析到节点输出的第一层字段，不会继续向对象内部做多级路径解析。复杂类型作为一个整体绑定给引用方，后面怎么拆，平台不管。

3.2 根因：插值引擎的路径解析边界

从实现上讲，Dify的变量绑定是面向“字段”的，不是面向“对象路径”的。节点输出在运行时是一个字段集合，每个字段值是字符串、数字、数组或JSON对象。模板插值引擎只负责把绑定的字段值渲染到对应位置，它不承担JSONPath式的深层下钻工作。所以{{#node.field.sub_field#}}这种写法在常规模板里天然不受支持。

很多从其他低代码平台转过来的朋友会不适应，因为在某些更灵活的低代码平台上，模板语法可以直接穿透到任意层级。Dify选择收敛这个能力，一方面是为了防止用户在模板里写出一长串不可维护的路径表达式，另一方面也是避免模板解析器承担过多业务结构理解职责。把结构拆解的活交给代码节点，边界反而清晰。

3.3 用代码节点把深层字段拆成扁平输出

明白根因，方案就很简单：不要指望模板下钻，在数据进入模板之前，先用一个代码节点完成拆解。我把上面的代码节点输出接进一个“字段提取”节点：

def main(company: dict) -> dict: return { "company_name": company.get("name", ""), "company_city": company.get("address", {}).get("city", "") }

这个节点只做一件事：把嵌套对象里的目标字段全部拍平成一层字段。之后LLM节点直接引用{{#extract.company_name#}}和{{#extract.company_city#}}，问题迎刃而解。

如果你懒得再加节点，也可以在原来那个调用外部接口的代码节点里，在返回字典里把需要扁平化的字段一并输出。两种做法本质都是“先拍平，再引用”。

提示：能通过变量面板选择解决的事，就不要塞进代码逻辑里硬解。把结构拆解放在显眼的中间节点上，对后续维护的人友好得多。

4. 子工作流与Agent节点：变量边界不是缺陷，而是协议

4.1 子工作流入口传参，是一条单向桥

Dify允许创建子工作流，作为可复用模块被其他流程调用。这个能力非常实用，但它同样遵守“只能引用一层”的规则：子工作流内部能访问的变量，只有子工作流开始节点定义的输入参数。父流程的中间变量，哪怕在调用节点旁边堆得满满当当，子流程内部一概看不见。

举个例子，我做过一个内容审核子工作流，入口先定义文档正文doc和审核规则rule两个参数。父流程调用时，除了doc和rule，我还想把操作员的权限等级permission传进去做差异化审核。如果不在调用节点的输入参数区域显式加上permission，子流程内部永远拿不到这个值。

这种设计一开始让人火大，但用几天后我反而觉得它像一种接口契约。子工作流一旦定义好入口参数，就是一份独立接口文档，任何人都能不看父流程就知道它需要什么、会产出什么。这比共享一片全局变量健康得多。

4.2 Agent节点内部步骤，默认不外泄

聊到Agent节点，也有类似的边界问题。Agent节点执行过程中会经历规划、调用工具、观察结果、生成回答等多个环节，这些中间产物在Agent节点内部是连续的，但对工作流外部并不暴露。外部节点只能引用Agent节点的最终输出，比如回答文本、使用到的工具列表。

如果你想用Agent内部某一次工具调用的结果作为后续节点输入，Dify默认做不到。正确做法是把那一步单独拆成一个普通节点放到工作流里，执行完再交给Agent去引用。这还是在贯彻同一个原则：每个节点是一个独立边界，边界内部不对外开源，对外只开放明确定义的输出。

4.3 边界清晰带来的三个实际收益

第一，调试定位快。工作流出问题时，顺着节点边界和变量引用关系，很快能锁定是哪一层数据没传到位。如果每个节点都持有全局句柄，排查链条会非常痛苦。

第二，模块可复用。子工作流因为边界干净，复制到任何新流程里都能用，不用关心被谁调用、上游给了什么额外变量。组内相互分享工作流模板时，几乎不用额外解释。

第三，依赖关系无环。把变量引用限制在作用域内，画布上的依赖图始终保持有向无环结构，平台可以放心做并发、缓存和回滚。这些收益在实际项目里确实能感受到，我们团队后来习惯性把大流程拆成多个子工作流，每个子工作流参数控制在三五个以内，维护起来明显轻松。

5. 绕过单层引用的四个通用套路与长期建议

5.1 先给场景配对方案

与其遇到一次绕一次，不如把这几个典型场景和对应方案记下来。我自己整理了一份常用对照：

这四组方案基本覆盖了日常90%的“单层引用”问题。核心原则一句话：Dify的变量传递是显式的，你需要什么数据，就把它放在离使用点最近的位置。

5.2 结构设计上的一些避坑经验

第一，开始节点不要只放用户输入。业务上确定的公共上下文，比如客户等级、渠道来源、租户ID这些，尽量也放到开始节点。平台对开始节点变量的可见范围通常最广，很多嵌套场景里它依然可用。

第二，进入循环之前一定要想清楚循环内部需要什么字段。因为一旦进了迭代，内部和外部之间的通信成本就很高。提前把一个元素需要用到的东西都塞进去，后面能少改很多。

第三，子工作流的参数建议精简，不要贪多。每次调整入口参数，所有调用方都可能跟着改。能用一两个结构化参数承载的信息，不要拆成四五个零散参数，否则调用节点配置会非常啰嗦。

第四，全局不变配置可以走环境变量。比如固定的企业名称、提示词里反复用的公共话术，用环境变量维护比每次跨节点传参稳定得多，也方便后续一处修改全局生效。

第五，调试时多利用运行记录里的变量快照。每次运行后查看中间节点的输出结构，比在模板里瞎猜准确得多。看到结构，就知道该在哪里拍平或中转。

5.3 我的长期建议：把“单层引用”当成设计约束

最后说点个人体会。最开始遇到“变量引用只能引用一层”时，我的情绪是烦躁的，总觉得凭什么不让我直接引用。但项目踩了几次坑后，我反而接受了这套规则，甚至觉得它帮我避免了很多潜在问题。

复杂流程最怕的不是限制多，而是数据依赖不可控。单层引用虽然让配置过程多了些拍平和传参动作，但它逼着你想清楚“数据从哪里来、要到哪里去”。每个节点都像中间转运站，变量像货物一程一程地接力，路径清晰，出问题就知道是在哪一程丢了。

如果你现在正被这个限制卡住，我建议先别抱怨平台，先去看你的数据结构。把数据结构拍平、把公共上下文放在该放的地方、把跨边界传递做成显式参数协议，你会发现“只能引用一层”根本不构成瓶颈，反而让整个工作流更好维护。

现在分享一个我后期养成的习惯：在动手拖节点之前，先在草稿纸上把变量流向写一遍，并且要求自己——每个节点只从直接可用的上一层拿数据。刚开始会觉得很麻烦，但坚持几周后，工作流设计速度明显变快，返工次数也少了很多。这个习惯，对比起在画布上边试错边调整的效率提升，相当明显。