> ## Documentation Index
> Fetch the complete documentation index at: https://cndoc-langchain.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Studio 故障排除

## Safari 连接问题

Safari 会阻止本地主机上的纯 HTTP 流量。当使用 `langgraph dev` 运行 Studio 时，您可能会看到“加载助手失败”的错误。

### 解决方案 1：使用 Cloudflare 隧道

<Tabs>
  <Tab title="Python">
    ```shell theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    pip install -U langgraph-cli>=0.2.6
    langgraph dev --tunnel
    ```
  </Tab>

  <Tab title="JS">
    ```shell theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    # 需要 @langchain/langgraph-cli>=0.0.26
    npx @langchain/langgraph-cli dev --tunnel
    ```
  </Tab>
</Tabs>

该命令会输出一个隧道 URL。要连接 Studio：

1. 复制隧道 URL（例如，`https://hamilton-praise-heart-costumes.trycloudflare.com`）
2. 在 `https://smith.langchain.com/studio/` 打开 Studio
3. 点击 **连接到本地服务器**
4. 粘贴隧道 URL 并将其添加到 **允许的来源**
5. 点击 **连接**

出于安全考虑，需要此手动步骤 - Studio 在连接到外部 URL 之前需要用户明确确认。

<Note>
  Cloudflare 隧道可能不可靠，并可能间歇性断开连接。
</Note>

### 解决方案 2：使用 Chromium 浏览器

Chrome 和其他 Chromium 浏览器允许在本地主机上使用 HTTP。使用 `langgraph dev` 无需额外配置。

## Chrome 连接问题

从 Chrome 版本 142 开始，当尝试通过 [`langgraph dev`](/langsmith/cli) 将 [LangSmith Studio](/langsmith/studio) 连接到您的本地开发服务器时，您可能会遇到“初始化 Studio 失败”的错误，并显示“TypeError: Failed to fetch”。即使 `http://127.0.0.1:2024/docs` 处的 API 服务器加载成功，也会发生这种情况。

**根本原因：** Chrome 142 完全强制执行私有网络访问 (PNA) 规范，没有回退机制，这默认阻止 HTTPS 站点（如 `https://smith.langchain.com`）访问 HTTP 本地主机服务器。

### 症状

* 运行 `langgraph dev` 可以成功启动服务器。
* 导航到 `http://127.0.0.1:2024/docs` 可以正确显示 API 文档。
* `https://smith.langchain.com` 上的 LangSmith Studio 显示：“初始化 Studio 失败 - 请验证 API 服务器是否正在运行或可从浏览器访问。TypeError: Failed to fetch”。
* 浏览器控制台显示类似错误：`Permission was denied for this request to access the 'unknown' address space`。

### 解决方案：在 Chrome 中允许本地网络访问

1. 在 Chrome 中打开 `https://smith.langchain.com` 上的 LangSmith Studio。
2. 点击地址栏左侧的 **锁图标**（或网站信息图标）。
3. 在下拉菜单中查找 **“本地网络访问”** 选项。
4. 将设置从 **“询问（默认）”** 或 **“阻止”** 更改为 **“允许”**。
5. 重新加载页面。

Studio 现在应该可以成功连接到您的本地开发服务器。

### 其他故障排除

**检查浏览器扩展冲突**

浏览器扩展（尤其是 Ollama Chrome 扩展或 AI 模型扩展）可能会干扰本地主机连接：

1. 暂时禁用所有浏览器扩展。
2. 重启 Chrome。
3. 尝试再次连接到 Studio。
4. 如果有效，请逐一重新启用扩展以找出问题所在。

**验证依赖项是否为最新版本**

```shell theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
pip install -U "langgraph-cli[inmem]"
```

**清除浏览器缓存和网站数据**

1. 在 Chrome 中，转到 **设置** > **隐私和安全** > **网站设置**。
2. 在列表中找到 `https://smith.langchain.com`。
3. 点击 **清除数据**。
4. 重启 Chrome 并重试。

## Brave 连接问题

当启用 Brave Shields 时，Brave 会阻止本地主机上的纯 HTTP 流量。当使用 `langgraph dev` 运行 Studio 时，您可能会看到“加载助手失败”的错误。

### 解决方案 1：禁用 Brave Shields

使用 URL 栏中的 Brave 图标为 LangSmith 禁用 Brave Shields。

### 解决方案 2：使用 Cloudflare 隧道

<Tabs>
  <Tab title="Python">
    ```shell theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    pip install -U langgraph-cli>=0.2.6
    langgraph dev --tunnel
    ```
  </Tab>

  <Tab title="JS">
    ```shell theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    # 需要 @langchain/langgraph-cli>=0.0.26
    npx @langchain/langgraph-cli dev --tunnel
    ```
  </Tab>
</Tabs>

该命令会输出一个隧道 URL。要连接 Studio：

1. 复制隧道 URL（例如，`https://hamilton-praise-heart-costumes.trycloudflare.com`）
2. 在 `https://smith.langchain.com/studio/` 打开 Studio
3. 点击 **连接到本地服务器**
4. 粘贴隧道 URL 并将其添加到 **允许的来源**
5. 点击 **连接**

出于安全考虑，需要此手动步骤 - Studio 在连接到外部 URL 之前需要用户明确确认。

## 图边缘问题

未定义的条件边缘可能会在您的图中显示意外的连接。这是因为如果没有正确的定义，Studio 会假设条件边缘可以访问所有其他节点。要解决此问题，请使用以下方法之一显式定义路由路径：

### 解决方案 1：路径映射

定义路由器输出与目标节点之间的映射：

<Tabs>
  <Tab title="Python">
    ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    graph.add_conditional_edges("node_a", routing_function, {True: "node_b", False: "node_c"})
    ```
  </Tab>

  <Tab title="Javascript">
    ```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    graph.addConditionalEdges("node_a", routingFunction, { true: "node_b", false: "node_c" });
    ```
  </Tab>
</Tabs>

<a id="python" />

### 解决方案 2：路由器类型定义

使用 Python 的 `Literal` 类型指定可能的路由目的地：

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
def routing_function(state: GraphState) -> Literal["node_b","node_c"]:
    if state['some_condition'] == True:
        return "node_b"
    else:
        return "node_c"
```

## Studio 中的实验故障排除

### **运行实验** 按钮被禁用

请检查以下内容：

* **已部署的应用程序**：如果您的应用程序部署在 LangSmith 上，您可能需要创建一个新版本才能启用此功能。
* **本地开发服务器**：如果您在本地运行应用程序，请确保您已升级到最新版本的 `langgraph-cli`（`pip install -U langgraph-cli`）。此外，请确保通过在项目的 `.env` 文件中设置 `LANGSMITH_API_KEY` 来启用跟踪。

### 评估器结果缺失

当您运行实验时，任何附加的评估器都会被安排在队列中执行。如果您没有立即看到结果，很可能意味着它们仍在等待处理。

***

<div className="source-links">
  <Callout icon="terminal-2">
    [将这些文档](/use-these-docs)通过 MCP 连接到 Claude、VSCode 等，以获取实时答案。
  </Callout>

  <Callout icon="edit">
    [在 GitHub 上编辑此页面](https://github.com/langchain-ai/docs/edit/main/src/langsmith/troubleshooting-studio.mdx) 或 [提交问题](https://github.com/langchain-ai/docs/issues/new/choose)。
  </Callout>
</div>