企业官网建设流程全解析

• 文档
• 提示工程
• 人工智能

导读

本文基于 Claude Code 系统提示词仓库中的 tool-description-artifact-external-resource-allowlist.md 展开，系统讲解 Artifact 页面在 CSP（内容安全策略）强制下允许加载的外部资源范围：五个脚本 CDN 主机、Google Fonts 字体链路，以及"其余一切皆被静默拦截"的边界。读完本文，你将掌握在 Claude Code 的 Artifact 查看器中正确引用第三方库与字体的唯一合法姿势——从精确版本号的 UMD 脚本到带真实回退栈的字体栈，并理解为什么页面自有 CSS、JS 与资源必须全部内联为 data: URI。

一、外部资源白名单的总体规则

Artifact 页面的查看器运行在一个由 CSP 锁定的沙箱框架中。该提示词文档开宗明义地给出了完整清单：

• 外部脚本只能从以下五个主机加载：
  • https://cdnjs.cloudflare.com（首选）
  • https://cdn.jsdelivr.net/npm/
  • https://unpkg.com
  • https://cdn.tailwindcss.com（Tailwind 的 play-CDN 脚本）
  • https://code.jquery.com
• 外部样式表只允许来自https://fonts.googleapis.com，而它所拉取的字体文件则来自https://fonts.gstatic.com（且每个字面都必须配备真实的回退字体栈）。

除上述主机之外的一切资源请求都会被静默拦截——没有任何可见报错。这意味着以下行为全部无效：

• 其他任何主机（esm.sh 也在禁止之列）；
• 即便在这五个白名单 CDN 上，非脚本类型的资源（样式表、图片、媒体文件）同样被拒绝；
• 对任意外部主机的fetch/XMLHttpRequest/WebSocket请求；
• 第三方库自身在运行时发起的网络请求（runtime fetches）。

因此，Artifact 页面的正确做法是：所有其余 CSS 与 JS 一律内联进页面，所有资源一律以 data: URI 形式内嵌。这条规则在 Claude Code 系统提示词中并非孤例，tool-description-artifact-page-implementation-requirements-app-wording.md 与 tool-description-artifact-design-fallback-requirements.md 中均有完全一致的白名单表述，只是后者强调这是在 Artifact 设计 skill 尚未加载、页面已先行书写时的兜底契约。

二、白名单的演进历史：从 CHANGELOG 看规则沉淀

这份白名单并非一成不变，仓库根目录的 CHANGELOG.md 完整记录了它的演进过程，可以作为理解"为什么是这五个主机"的历史证据：

1. 最初，Artifact 的外部脚本源只有少量受限 CDN，非脚本资源与页面自有代码必须内嵌（见 CHANGELOG 第 685 行附近：允许从 CSP 批准的 CDN 主机加载固定版本（pinned）的 UMD 脚本，优先使用 cdnjs，并要求库脚本必须放在依赖它的内联脚本之前，同时继续要求非脚本资源与页面自有代码内嵌）。
2. 随后，Artifact external resource allowlist 与 Artifact page implementation requirements（app wording）两个文档片段同步新增https://unpkg.com进入外部脚本 CDN 白名单（CHANGELOG 第 238 行附近），与既有脚本主机并列。
3. 再之后，Artifact design fallback requirements 进一步放宽允许的外部脚本源为 cdnjs（首选）、jsDelivr、unpkg、Tailwind CDN 与 jQuery（CHANGELOG 第 144 行附近），形成当前五主机格局。

这条历史脉络说明：白名单是"逐主机评审后放行"而非"开放任意 CDN"，新增主机都伴随明确的使用场景（如 Tailwind 的 play-CDN 服务于零构建的样式方案），且"优先 cdnjs、精确固定版本"的原则始终不变。

三、如何正确加载一个第三方库

tool-description-artifact-publishing-and-update-guidance.md 给出了加载库的规范 URL 形态：

<script src="https://cdnjs.cloudflare.com/ajax/libs/<lib>/<exact version>/<file>"></script>

三条硬性要求：

1. 选择 UMD 构建：UMD 构建会定义全局变量，例如 React 的react/18.3.1/umd/react.production.min.js，随后再加载react-dom的对应 UMD 文件；
2. 必须固定精确版本号（<exact version>不可省略），杜绝浮动的 latest / 主版本号通配；
3. 库脚本必须放在使用它的内联<script>之前——依赖顺序是加载成功的前提，这与浏览器同步脚本的天然执行顺序一致。

一个典型的组合加载示意：

<!-- 先加载库（精确版本 + UMD 全局） --> <script src="https://cdnjs.cloudflare.com/ajax/libs/react/18.3.1/umd/react.production.min.js"></script> <script src="https://cdnjs.cloudflare.com/ajax/libs/react-dom/18.3.1/umd/react-dom.production.min.js"></script> <!-- 后写使用库的内联脚本 --> <script> const root = ReactDOM.createRoot(document.getElementById("app")); root.render(React.createElement("h1", null, "Hello")); </script>

注意：这里<script src>是白名单唯一放行的"外部资源"形态，而业务逻辑代码永远以内联形式存在，不单独成文件外链。

四、字体加载规范：Google Fonts 链路与回退栈

样式表唯一的外链出口是 Google Fonts：在<head>中以<link rel="stylesheet" href="https://fonts.googleapis.com/...">引入字体族，浏览器随之从https://fonts.gstatic.com拉取字体文件。这一点在仓库的 Slides 工作流中有真实可循的用法——system-reminder-new-slides-deck-parallel-appifactrepl-workflow.md 的 deck 索引示例中就写明了字面配置：

deck.faces = { lora: { family: "Lora", href: "https://fonts.googleapis.com/css2?family=Lora:wght@400;600&display=swap" } };

文档同时强调：每个字面（face）都必须配备真实的回退字体栈（fallback stack）。原因是字体文件加载在沙箱内同样可能失败或被延迟，没有回退栈的页面会退回丑陋的系统默认字体甚至出现不可读内容。例如使用 Lora 时应写成：

font-family: "Lora", "Georgia", "Times New Roman", serif;

五、被静默拦截的边界：明确"做不到"清单

白名单的反面是强约束，文档用"没有可见错误"（no visible error）来描述拦截方式——页面无法通过报错感知资源被拒绝，因此必须从设计层面规避而非运行时探测。结合 tool-description-artifact-publishing-and-update-guidance.md 中对查看器框架的整体说明，以下能力在 Artifact 中一律不可用：

这也是为什么 tool-description-artifact-page-implementation-requirements-app-wording.md 明确要求：表单提交必须在脚本中preventDefault()处理、确认步骤要构建进页面本身、文件不能通过普通链接提供、mailto:/tel:/sms:链接只作为"可能无效的便利"并同时展示可选中复制的文本。此外该文档还补充了与外部资源强相关的两条配套约束：

• 页面大小：渲染后的页面（含内嵌 data: URI）不得超过MAX_ARTIFACT_BYTES（换算为 MB 的配置变量）——内联策略会膨胀 HTML 体积，因此 data: URI 的体积被明确计入上限；
• 资源内联的物理基础：tool-description-artifact-html-document-skeleton.md 说明发布时页面会被包裹进<!doctype html>骨架，head 中只有 charset、viewport 与最小 reset，作者需自行在文件顶部放置<title>与<style>——这恰好是"全部内联"策略下的常规书写位置。

六、实战落地清单

综合白名单文档及其配套约束，写一个合规的 Artifact 页面应遵循以下顺序：

1. 盘点依赖：仅允许 UMD 构建的库脚本，且只从 cdnjs（首选）、jsDelivr、unpkg、Tailwind CDN、jQuery CDN 五者中选择；其余任何库一律放弃外链；
2. 精确固定版本：<lib>/<exact version>/<file>三段式 URL，UMD 全局变量先行定义，库脚本置于使用它的内联脚本之前；
3. 字体走 Google Fonts：样式表外链仅限fonts.googleapis.com，字体文件来自fonts.gstatic.com，每个字面配真实回退栈；
4. 其余全部内联：自有 CSS、自有 JS、图片图标与媒体一律转 data: URI 嵌入，并复核总大小不超过 MAX_ARTIFACT_BYTES；
5. 绕开被拦能力：不提供下载链接、打印按钮、alert 确认、外部 fetch，表单提交与确认逻辑构建在页面脚本内，#anchor之外的 URL 状态一律不进location.hash。

七、总结

Artifact 外部资源白名单是一份"封闭默认（deny by default）+ 少量显式放行（explicit allow）"的 CSP 策略：脚本只认五个 CDN 主机的精确版本 UMD，样式只认 Google Fonts 链路，其余一切（包括 esm.sh、同 CDN 的非脚本资源、所有运行时网络请求）都被无痕拦截。对 Claude Code 而言，这条提示词直接决定了 Artifact 页面的编写范式——"能外链的极少，能内联的必须内联"；对开发者而言，理解这份白名单是排查"资源加载失败却无报错"类问题的第一把钥匙。其演进记录（CHANGELOG.md）也表明这是一份随版本评审更新的活文档，实际以当前 ccVersion 对应的系统提示词为准。

• 文档
• 提示工程
• 人工智能