浏览器项目里的库和 CDN

您让 Claude Code 在浏览器里做一个国际象棋游戏。打开页面一看：棋盘在，棋子摆好了，兵会乖乖跟着鼠标走。可以下棋了。但为了测试，您把它一下子往前拖了三格 - 它就停在那儿了。接着您又试着让黑方连走两步。页面照样没有拦着。

在走这两步之前，项目看起来几乎完工了。现在才发现，最要紧的部分还不能用：没有人在核实规则。可以让智能体禁止兵这样走。但接下来就得处理走子顺序、将军、王车易位、兵的升变。每次修好一处，都会留下一个问题：还有哪个条件被漏掉了？

这时候值得停下来，为这个任务找一找现成的代码。国际象棋的规则已经在库 chess.js 里实现好了。把一步棋交给它，就能拿到核实的结果。这样一来，自己写的代码就只负责一条清楚的链路：从棋盘取得动作，交给库核实，再把正确的局面显示出来。

剩下的事，是把库送进浏览器，接入页面的运行流程。办法之一是通过 CDN 用链接加载它。下面我们来拆解这是怎么运作的，以及为什么代码里多了一条链接，还不代表兵就不能乱走了。

库做什么

库是别人写好的代码，您把它接入自己的项目，这样就不用把已经写过的东西再写一遍。chess.js 正是这样：它知道每个棋子怎么走，知道什么是将军和王车易位，能列出当前局面下所有合法的走法，还能判断对局是否结束。

这里很容易掉进一个陷阱：接入库，然后等着游戏自己跑起来。不会的。库把规则和对局的局面存在自己的内存里，它什么都不画，也完全不知道页面上有一个棋盘。

看看普通一步棋会发生什么。您把兵从 e2 拖到 e5。界面捕捉到了拖动，连接代码问库"这一步合法吗"，库回答"不合法" - 连接代码就把棋子送回 e2。如果没有人提出这个问题，兵就会安然落在 e5：页面没有任何东西会阻止把它画在那里。

两条分支都以同一个动作结尾：连接代码显示库给出的局面。走法合法之后局面是新的，不合法之后局面维持原样，于是棋子回到原来的格子。

由此可以看出该怎样表述任务。"接入 chess.js" 这个要求可以照字面完成 - 出现一行加载代码，仅此而已。要提的是那条链路：棋盘上的走法交给库，库的回应决定要不要移动棋子，走法之后的局面来自库的状态，而不是您松开鼠标的那个位置。

浏览器怎样通过 CDN 拿到代码

库文件总得从某处拿来。可以下载下来放在页面旁边，也可以在页面代码里指向外部服务上的这个文件。为此常用的是 CDN（Content Delivery Network，内容分发网络）。它是一组从不同地点向用户分发文件的服务器。图片、样式表和 JavaScript 库都常通过 CDN 分发。在我们的例子里，库文件由 jsDelivr 服务提供。

您打开页面时，浏览器读取页面代码，遇到指向库的链接。它按这个地址请求文件，加载完成后再执行调用这个库的页面代码。库运行在用户的浏览器里。 CDN 只负责分发它的代码；国际象棋走法的核实已经在您自己的设备上进行。

图中的方框把浏览器和外部服务分开。加载完成后，库就在页面内部：连接代码就在那里调用它。不需要每一步棋都发给 CDN。

对 chess.js 来说，接入代码是这样的：

<script type="module">
  import { Chess } from 'https://cdn.jsdelivr.net/npm/chess.js@1.4.0/+esm'

  const chess = new Chess()
  console.log(chess.fen())
  // rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1
</script>

这里有三个关键细节。第一是 type="module"。库以 ES 模块的形式送达，只有通过 import 才能从中取出 Chess；普通的 <script src="..."> 标签根本解析不了这个文件 - 它会在文件里的 export 上报错。有些库还提供不带模块的老式发布方式：那种情况下普通标签就够了，页面上会自动出现一个全局变量。chess.js 没有这种打包方式，所以只有这一种选择。

第二个细节是版本号直接写在地址里，chess.js@1.4.0。接入方式和方法名都要按链接里这个版本的文档来。没有版本号的地址迟早会指向另一个文件，按旧文档写的代码就会跑不通。

第三个细节最不起眼 - 地址末尾的 /+esm。这不是装饰，而是要求 CDN 专门按模块的形式打包这个文件：没有它，同一个地址会拿到另一种打包结果，import 就什么都找不到。

不用把整个游戏搭出来，也能确认库确实加载成功了 - 在同一个 <script type="module"> 里加几行代码，打开浏览器控制台（开发者面板的 Console 标签，F12 或 Ctrl+Shift+I）：

// 白兵从 e2 直接走到 e5 不会成功
try {
  chess.move('e5')
} catch (error) {
  console.log('走法被拒绝:', error.message) // Invalid move: e5
}

chess.move('e4')          // 这一步库会接受
console.log(chess.turn()) // b，轮到黑方

控制台里的起始局面、被拒绝的走法，以及 e4 之后轮到黑方 - 这些说明文件已经到位，规则也在正常运作。接下来只剩把它们和棋盘连起来。

还有一点要说清楚，免得产生错觉。CDN 并不能消除对网络的依赖。浏览器可能会重复使用缓存里已经保存的文件副本，所以不是每次打开页面都要重新下载。但如果没有合适的缓存副本，CDN 又不可用，库就加载不了，游戏也就没法用它的规则来运行。

和 Claude Code 配合时怎么做

"通过 CDN 接入库" 这样的要求，给智能体留下了好几个要决定的地方：从哪里拿文件、选哪个版本、怎样在这个页面里加载它、用什么来确认结果。不如把这些决定直接写进任务里。下面是针对不同情况的提示词；不必每个都发一遍。

选定接入用的链接

如果智能体提议用某个库，先让它把在您项目里的接入方式搞清楚。这样您就能拿到一个具体的地址，以及它是从哪儿来的说明。

看看我的页面现在是怎么写的，检查 chess.js 是不是已经接入了。
在库的文档和 jsDelivr 里找一个适合浏览器的 CDN 加载方式。
给出带具体版本号的 URL，并解释地址里每一部分的意思。
附上文档链接。先不要改代码。
如果没能核实文档，就直接告诉我。

在回复里找版本号、接入方式和选择的理由。只给一句"这是能用的链接"是不够的：光看这句话，不知道智能体有没有对照过文档，也不知道这个文件是否适合您的页面。

把库接到棋盘上

地址选定之后，给智能体一个能看到结果的任务。对于简单的 HTML 页面，可以直接说明您想保留现有的启动方式。

按选定的 CDN 地址、固定版本接入 chess.js。
保留页面现有的启动方式。把库和棋盘连起来：
把每一步棋交给它，并按它的状态显示局面。
遇到不合法的走法，把棋子送回原来的格子。
说明接入代码加在哪里，库的回应又是在哪里处理的。

这里有两个独立的结果：浏览器拿到了库，棋盘上的操作也开始经过它的规则核实。让智能体把代码里的这两处都指出来，您就能看清它具体加了什么。

在浏览器里核实结果

HTML 里出现链接，只能证明文件被改过。下面这个任务能帮您核实加载本身和游戏的实际行为。

打开页面，在开发者面板的 Network 标签里检查 chess.js 是否加载成功。
检查 Console 里有没有错误。然后从初始局面试着走 e2-e5：
这一步应该被拒绝，兵留在 e2。之后再走 e2-e4：
这一步应该成功，轮到黑方走。
汇报每一步观察到的情况。如果你没有浏览器访问权限，
给我简短的核实步骤，并说明你自己没有核实过。

Network 标签显示的是页面的网络请求，Console 显示的是页面代码的消息和错误。如果文件加载成功，但兵依然能走到 e5，就该去走法处理那部分找原因了。单单换一个 CDN 链接解决不了这个问题。

排查加载错误

出问题时，把 Console 里的准确错误文本和 Network 里失败请求的地址一起交给智能体。这样它就能核实具体原因，而不是挨个试链接。

接入库之后页面报错了。
Console 里的文本：[把消息整段粘贴进来]。
Network 里的 URL 和请求结果：[把地址和状态粘贴进来]。
检查文件是否可以访问、它的格式是否适合我们的 import 方式，
以及代码里的名称是否和所选版本的文档一致。
先根据这些信息说明原因，再做最小的修正并重新核实。
不要同时改动 CDN、版本和游戏代码。

把方括号里的内容换成您自己的数据。如果 Network 里根本没有库的请求，也照实写出来：这本身就是有用的线索。修好之后，重新核实那两步棋，确认整条链路都正常了。

预先处理 CDN 不可用的情况

如果库没能加载，一个看起来能用的棋盘可能会让人误以为还能继续玩。让智能体把这种状态明确地告诉用户。

处理 chess.js 从 CDN 加载失败的情况。
库没准备好之前，不允许走棋。出错时显示
清楚的提示，并提供重新加载页面的办法。
先在 CDN 请求被屏蔽的情况下核实这个行为，
再在解除屏蔽之后核实一次。注意缓存：单纯断网
可能仍然能用到之前已经加载好的副本。说明你具体是怎么核实这次故障的。

这类核实最好单独进行，不要和正常对局混在一起。结果应该能看到两种清楚的状态：库可用，走法正常核实；加载失败，页面解释了为什么现在还不能玩。