可行但需用type="module"引入esm兼容cdn（如esm.sh），或降级使用已废弃的apollo boost v2 umd包；因v3+无umd版本且依赖es模块语法，直接script引入会报referenceerror。
直接在 index.html 中集成 Apollo Client 是可行的，但必须绕过模块系统、跳过构建步骤，并手动处理依赖加载顺序——否则会遇到 ReferenceError: ApolloClient is not defined 或 GraphQL parse error: Unexpected Name "gql" 这类报错。
为什么不能直接 script 标签引入 @apollo/client？
Apollo Client v3+ 是 ESM 模块，不提供 UMD 版本；@apollo/client 包内部依赖 graphql 的解析器和缓存逻辑，且大量使用 export/import 语法。直接用 <script src="node_modules/..."></script> 会失败。
- CDN 上的
@apollo/client@3.x官方未托管可直接执行的浏览器版 bundle（不像vue或alpinejs） -
graphql包本身也无浏览器就绪的全局变量导出，默认只支持 Node.js 或打包后使用 -
gql模板标签函数不是原生语法，需通过graphql-tag或 Apollo 自带的轻量解析器补全
真正能用的 HTML 集成方案：CDN + 手动 bundle
目前唯一稳定、零构建、适用于纯 HTML 场景的方式是使用预构建的 umd 兼容 bundle，例如由 Skypack 或 esm.sh 动态生成：
<script type="module">
import { ApolloClient, InMemoryCache, createHttpLink, gql } from 'https://www.php.cn/link/83b3b79f3802894efd6dec0c0e452e5b@apollo/client@3.10.0';
import { setContext } from 'https://www.php.cn/link/83b3b79f3802894efd6dec0c0e452e5b@apollo/client/link/context';
const httpLink = createHttpLink({
uri: 'https://your-api.com/graphql'
});
const authLink = setContext((_, { headers }) => {
const token = localStorage.getItem('auth-token');
return {
headers: {
...headers,
authorization: token ? `Bearer ${token}` : ''
}
};
});
const client = new ApolloClient({
link: authLink.concat(httpLink),
cache: new InMemoryCache()
});
// 示例查询（注意：不能在 module script 外调用 useQuery —— 那是 React Hook）
client.query({
query: gql`query { viewer { login } }`
}).then(result => {
console.log(result.data);
document.getElementById('login').textContent = result.data.viewer.login;
});
</script>
- 必须用
type="module"，否则import会报错 -
gql在此上下文中可用，因为 esm.sh 已做运行时 polyfill - 不要尝试在非 module script 中 import —— 浏览器不支持跨 script 的顶层 await 或共享模块作用域
- 无法使用
useQuery/useMutation等 React Hook，它们强依赖 React 渲染周期
替代方案：用 Apollo Boost（仅限 v2，已废弃但 HTML 友好）
如果你坚持纯静态 HTML + 最小侵入，Apollo Boost v2 是最后一个提供 UMD 构建的版本（apollo-boost@2.4.9），它把 apollo-client、graphql、graphql-tag 打包进一个全局 ApolloBoost 对象：
<script src="https://unpkg.com/apollo-boost@2.4.9/umd/apollo-boost.min.js"></script><script>
const client = new ApolloBoost.ApolloClient({
uri: 'https://your-api.com/graphql'
});
client.query({
query: ApolloBoost.gql`query { hello }`
}).then(...);
</script>
- 优点：无需
type="module"，兼容 IE11（需额外 polyfill） - 缺点：无缓存策略控制、不支持
link链式扩展、不支持订阅、已于 2021 年停止维护 - 重要：v3+ 的所有文档、错误提示、社区示例都不适配此路径，调试成本高
真正关键的一点是：HTML 集成 Apollo 不是“能不能”，而是“值不值得”。一旦你需要响应式 UI 绑定、错误重试、缓存更新联动或 fragment 复用，就必须走向组件框架（React/Vue/Angular）或 Alpine.js 这类声明式绑定层——纯 HTML + Apollo 的组合，只适合一次性数据快照渲染或原型验证。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
