Cursor 的 deeplink 打不开：链接格式与系统关联

团队里有人整理了一条好用的 prompt，或者把一条 rule 调顺了，想分享出去，最省事的办法是发一条链接。Cursor 官方文档里有专门一页讲这个，叫《Deeplinks》（cursor.com/docs/reference/deeplinks）。链接发出去之后最常见的反馈只有两句：「我点了没反应」和「打开了，但里面是空的」。

这两句话背后其实是完全不同的两类原因：一类出在链接本身的格式上，一类出在收链接的那台机器有没有把 cursor:// 这个协议关联到 Cursor。这两类的判定方法不一样，处置方法也不一样，混在一起查会越查越乱。下面按现象 → 判定 → 处置 → 验证 → 排除的顺序走一遍，依据只有官方文档写明的那些内容。

先把链接的四段结构记住

文档在三个小节里各给了一组生成代码，把它们放在一起看，链接的结构是一样的四段：

段位	取值	文档出处
协议 / 域名（base URL）	cursor://anysphere.cursor-deeplink/ 或 https://cursor.com/link/	FAQ「How do I use deeplinks on the web instead of in the Cursor app?」
类型	prompt、command、rule	文档正文的三个小节
参数 name	command 与 rule 用，prompt 不用	各节的生成示例
参数 text	三类都用，放正文内容	各节的生成示例

这张表是我按那一页的三段示例代码归纳出来的，四段里任何一段写错，表现都是「打不开」或者「打开了是空的」。文档正文只写了 prompt、command、rule 这三类；同一套 cursor://anysphere.cursor-deeplink/ 前缀在《Plugins》页（cursor.com/docs/plugins）里还有一个 MCP 安装用的形态，那一节写明的形式是：

cursor://anysphere.cursor-deeplink/mcp/install?name=$NAME&config=$BASE64_ENCODED_CONFIG

注意它的 config 参数在文档里写明是 base64 编码过的内容，和上面三类的 text 不是一回事。那一节还指向了另一页专门讲这类安装链接怎么生成，本文不展开。

现象一：点了完全没反应

怎么确认是这个问题。 官方文档 FAQ 里给了一条现成的等价转换，正好可以当判定动作用：把 base URL 从 cursor://anysphere.cursor-deeplink/ 换成 https://cursor.com/link/，其余部分原样不动。文档里给的对照例子就是这两行：

cursor://anysphere.cursor-deeplink/prompt?text=Hello%20world

https://cursor.com/link/prompt?text=Hello%20world

把手上这条链接照这个规则换一次，再打开：

• 换成 https:// 之后能正常走到 cursor.com，说明链接本身的类型段和参数段是对的，问题出在本机没有把 cursor:// 交给 Cursor 处理；
• 换了之后仍然不对，那就不是协议关联的事，跳到下面的现象二。

处置。 官方文档写明的只有那条转换规则本身——用 web 形态的链接绕开直接唤起。至于 cursor:// 这个自定义协议在各操作系统上由谁注册、注册项叫什么、怎么重新注册，Cursor 官方文档没有说明这一点，我们也就不编。

这里要按系统分开说，而且下面这段属于通用做法，不是 Cursor 官方文档的内容，只是用来判断「系统层有没有人接管这个协议」：

• Windows：自定义协议由本机的协议关联表决定归谁处理。想单独试一下协议本身通不通，可以在命令提示符里让系统自己去解析这条 URL：

  start "" "cursor://anysphere.cursor-deeplink/prompt?text=Hello%20world"
  

  如果系统提示找不到可以打开此类链接的应用，说明关联缺失，跟链接内容无关。注意 Windows 下这条命令里的引号不能省：& 在命令行里有特殊含义，参数里带 & 的长链接不加引号直接粘进去容易被从中间截断——这一点在类 Unix 的 shell 里同样存在，只是 Windows 侧读者更常踩到。

• macOS / Linux：macOS 上对应的动作是 open "cursor://..."，Linux 桌面上一般是 xdg-open "cursor://..."，作用相同，都是把这条 URL 交给系统的默认处理程序。

以上为按官方文档中的参数语义组合的示例，未经实测，以官方文档最新内容为准。这几条系统命令的行为以你所用系统的实际表现为准。

处置后怎么验证。 用文档 FAQ 里那条 Hello%20world 的原始例子重新走一遍——它足够短、编码简单，能排除内容本身的干扰。这一条能唤起，说明协议这一层通了。

什么情况说明不是这个原因。 如果换成 https://cursor.com/link/ 形态也一样打不开，或者同一条链接在另一台机器上能唤起 Cursor，那问题就不在协议关联上，别再折腾系统设置。还有一种很容易误判的情况：链接确实唤起了 Cursor，只是没有自动开始跑——那不是故障，见最后一节。

现象二：打开了，但内容是空的或者不完整

怎么确认是这个问题。 把链接按上面那张四段表逐段对一遍，重点看两处：

1. 类型段拼对了没有。 文档正文只写了 prompt、command、rule 三类，路径段写成别的词，文档里没有对应说明。
2. 参数名给全了没有。 文档的示例代码写得很清楚：prompt 那一节只 set 了 text；command 与 rule 两节都 set 了 name 和 text 两个参数。分享 command 或 rule 时漏掉 name，是最容易犯的一类错。

更省事的判定办法是别手拼，直接用文档给的生成函数重新生成一条，再和手上这条比对。TypeScript 版的 prompt 生成函数，文档原文是这样：

const IS_WEB = false; // Set to true for web format

function generatePromptDeeplink(promptText: string): string {
  const baseUrl = IS_WEB
    ? 'https://cursor.com/link/prompt'
    : 'cursor://anysphere.cursor-deeplink/prompt';
  const url = new URL(baseUrl);
  url.searchParams.set('text', promptText);
  return url.toString();
}

command 那一节的 Python 版，文档原文是：

from urllib.parse import urlencode, urlparse, urlunparse

IS_WEB = False  # Set to True for web format

def generate_command_deeplink(command_name: str, command_content: str) -> str:
    base_url = "https://cursor.com/link/command" if IS_WEB else "cursor://anysphere.cursor-deeplink/command"
    params = {"name": command_name, "text": command_content}
    query_string = urlencode(params)
    return f"{base_url}?{query_string}"

这两段代码里真正值钱的是同一件事：编码交给标准库做。TypeScript 版用 url.searchParams.set()，Python 版用 urlencode()，都不是把字符串拼起来了事。prompt 和 command 的正文里几乎一定有空格、换行、引号、&，手拼时漏掉编码，链接就可能在某个字符处断掉——表现出来正是「打开了但内容缺一截」。需要说明的是，「编码没做对会导致内容缺一截」这层因果属于 URL 编码的通用常识，不是 Cursor 官方文档写明的内容；文档那一页只给了用标准库生成链接的示例，并没有描述编码出错时会是什么表现。文档里还有一处提示同样指向编码：FAQ 讲长度限制时，写的是按 URL-encoded 之后的长度算，也就是说编码后的长度才是有效长度。

文档语义给出的处置。

• 用上面两段官方示例代码重新生成链接，别手拼；
• 内容太长时，文档 FAQ 写明 deeplink URL 存在一个最大长度上限，超过就不适合再走链接分享（具体上限数值以官方文档 FAQ 页为准，这类阈值随版本可能调整）。这种情况更适合改走仓库：command deeplink 分享的是 .cursor/commands 目录下的自定义 command，rule deeplink 分享的是 .cursor/rules 目录下的自定义 rule，内容长的时候，把文件提交进仓库让同事拉下来，比塞进 URL 更稳。

处置后怎么验证。 生成完先自己完整看一遍这条 URL：类型段、name、text 三处是不是都在，text 里的空格是不是已经变成编码形式。再让链接走一遍上面那条 web 转换——https://cursor.com/link/... 与 cursor://... 用的是同一套路径与参数，一处对了另一处也就对了。

什么情况说明不是这个原因。 如果同一条链接换一个更短、纯英文无符号的 text 也照样是空的，那基本可以排除编码与长度，回头查现象一的协议关联；如果链接唤起后 Cursor 里确实拿到了内容、只是还没跑，那两类原因都不是——那是文档写明的行为。

最后一类：它本来就不会自动执行

这一条单独拎出来说，因为把它当故障查最浪费时间。官方文档在 prompt 那一节写得很直白：deeplink 打开后是把 prompt 预填进 chat，「The user must review and confirm the prompt before it gets executed」，后面还跟了一句 “Deeplinks never trigger automatic execution”——文档写明 deeplink 从不触发自动执行。

三类的措辞略有差别，值得对着看一眼：prompt 与 command 两节写的是用户确认之后才 executed，rule 那一节写的是确认之后才 added（被加进来）。也就是说，rule 走的是「加进环境」的动作，另外两类走的是「准备好待执行」。这是把文档里三处措辞放在一起得到的差别，文档没有再解释更多，我们也就到此为止。

顺带一提文档里那句安全提醒，它写在正文很靠前的位置：分享之前务必检查 prompt 与 command 里有没有 API key、密码或者私有代码。这类内容一旦进了 URL，就跟着链接进了聊天记录、工单和搜索引擎。真要往示例里写密钥，请写成 <YOUR_API_KEY> 这样的占位。另外文档 FAQ 也写明，web 形态的链接会把人带到 cursor.com，由用户在那里打开或者复制下来在 Cursor 里用——把这两处放在一起看，web 形态解决的是「链接能不能被分发和打开」，最终仍然需要有一个 Cursor 环境去接收它，它并不替你省掉本机那一步。

Cursor 迭代频繁，上面涉及的链接格式、参数与长度限制都随版本变动，动手前请以官方文档《Deeplinks》页的最新内容为准。

---

本文依据 Cursor 官方文档（cursor.com/docs 与 cursor.com/help）于 2026-08-18 的公开内容整理。 该产品闭源，本文只复述官方文档写明的机制，不推断其内部实现； 我们没有对文中涉及的功能做过实测，因此不涉及界面外观、操作手感与运行速度的任何描述。 该产品迭代频繁，文中涉及的设置项与命令随版本变动，请以官方文档最新内容为准。 本文不涉及订阅价格、额度与模型清单，相关信息请以官方定价与模型说明页为准。

安全与合规相关做法请结合自身环境评估，本文不构成安全方案建议。