VitePress 默认主题 Carbon Ads 广告接入指南配置、加载原理与样式定制【免费下载链接】vitepressVite Vue powered static site generator.项目地址: https://gitcode.com/gh_mirrors/vi/vitepressVitePress 的默认主题内置了对 Carbon Ads、types/default-theme.d.ts、src/node/plugin.ts深入讲解配置方法、加载原理、样式定制与按需优化读完即可为你的 VitePress 站点接入 Carbon Ads 广告。一、Carbon Ads 是什么为什么用默认主题内建支持Carbon Ads 是一项面向开发者社区的广告投放服务常见于各类技术文档站、开源项目官网。其广告形态为原生文字 图片组合与文档阅读氛围契合度较高。VitePress 默认主题把它作为官方支持的广告方案之一只要在themeConfig中配置carbonAds字段无需编写任何组件代码广告就会出现在文档页右侧栏。与自行手工嵌入脚本相比内建支持具备以下优势由主题统一管理挂载点与卸载逻辑不会污染布局仅在桌面宽屏侧边栏可见时加载脚本避免移动端浪费流量页面切换时自动刷新广告refresh保证每次路由变化都展示新广告。二、最小接入三行配置启用 Carbon Ads在 VitePress 的配置文件如 docs/config.ts中于themeConfig下新增carbonAds对象即可启用export default { themeConfig: { carbonAds: { code: seu-código-carbon, placement: sua-veiculação-carbon, format: classic } } }字段含义如下与葡萄牙语文档docs/pt/reference/default-theme-carbon-ads.md保持一致配置项必填说明code是Carbon Ads 分配的广告位代码serve 参数在 Carbon Ads 平台后台获取placement是投放标识placement 参数同样由平台分配format否广告展示格式可选classic、responsive、cover默认classic设置完成后运行vitepress dev或vitepress build即可在文档页右侧栏看到广告位若留空或不配置carbonAds字段广告功能完全关闭页面不会有任何额外脚本。三、配置项的类型约束与默认值在类型定义文件 types/default-theme.d.ts 中CarbonAdsOptions接口精确约束了合法取值// carbon ads ---------------------------------------------------------------- export interface CarbonAdsOptions { code: string placement: string format?: classic | responsive | cover }code与placement为必填字符串format为可选枚举仅接受classic | responsive | cover三种字面量传入其他字符串会在 TypeScript 编译阶段直接报错配置项在 ThemeConfig 中声明为可选carbonAds?: CarbonAdsOptions注释明确说明不定义即关闭广告功能Leave it undefined to disable the ads feature。format的三个取值对应不同广告尺寸策略classic经典固定尺寸如 300×250布局稳定responsive自适应响应式尺寸随容器宽度变化cover覆盖式大尺寸展示视觉冲击力更强。需要强调的是format仅影响加载脚本时传递给 Carbon CDN 的 URL 参数具体渲染由 Carbon 服务端决定VitePress 端不参与广告内容的排版计算。四、底层原理CDN 脚本是如何被拼装与注入的原文档给出了脚本 URL 的拼接模板//cdn.carbonads.com/carbon.js?serve${code}placement${placement}format${format}这段逻辑在源码中有完整实现。核心组件 VPCarbonAds.vue 的init()函数使用URLSearchParams构造查询参数并动态注入script标签function init() { if (!isInitialized) { isInitialized true const params new URLSearchParams({ serve: carbonOptions.code, placement: carbonOptions.placement, format: carbonOptions?.format || classic }) const s document.createElement(script) s.id _carbonads_js s.src //cdn.carbonads.com/carbon.js?${params.toString()} s.async true container.value?.appendChild(s) } }几个值得注意的实现细节默认值兜底carbonOptions?.format || classic—— 即使配置中省略format实际请求 URL 也会带上formatclassic脚本 ID 固定s.id _carbonads_jsCarbon 官方脚本会识别该 ID 并注入广告内容避免重复加载异步加载s.async true保证广告脚本不会阻塞文档主内容的渲染协议相对 URL使用//cdn.carbonads.com/...形式自动适配当前页面的 http/https 协议。五、按需加载与路由刷新性能友好的设计广告脚本并非一进入页面就无条件加载。VPCarbonAds.vue 通过useMediaQuery((min-width: 80rem))检测侧边栏是否可见if (carbonOptions) { onMounted(() { // if the page is loaded when aside is active, load carbon directly. // otherwise, only load it if the page resizes to wide enough. this avoids // loading carbon at all on mobile where its never shown if (isAsideVisible.value) { init() } else { watch(isAsideVisible, (visible) visible init()) } }) }这意味着在移动端视口小于 80rem即 1280px广告位不展示脚本也不会加载避免无谓的流量消耗用户从手机横屏切换到桌面视口时watch监听到isAsideVisible变为true才触发首次加载广告初始化后组件监听路由变化route.data.relativePath在_carbonads_js已存在且侧边栏可见时调用(window as any)._carbonads?.refresh()刷新广告实现单页应用内页面切换即换广告的效果见 VPCarbonAds.vue。六、编译期优化__CARBON__标志与零成本按需打包VitePress 在构建阶段会根据是否配置了carbonAds向客户端代码注入一个编译期常量__CARBON__。相关实现在 src/node/plugin.tsdefine: { ... __CARBON__: !!site.themeConfig?.carbonAds, ... }该常量被 VPDocAsideCarbonAds.vue 用于条件加载广告组件const VPCarbonAds __CARBON__ ? defineAsyncComponent(() import(./VPCarbonAds.vue)) : () null其效果是未配置carbonAds的站点__CARBON__为falseVPCarbonAds被替换为空组件且VPCarbonAds.vue不会被打进产物包实现零体积成本配置了carbonAds的站点使用defineAsyncComponent将广告组件拆分为独立异步 chunk按需加载不影响首屏体积。七、展示位置文档页右侧栏的广告插槽广告位挂载在文档页的右侧边栏Doc Aside中位于大纲Outline与页脚之间的 spacer 之后。见 VPDocAside.vuediv classspacer / slot nameaside-ads-before / VPDocAsideCarbonAds v-iftheme.carbonAds :carbon-adstheme.carbonAds / slot nameaside-ads-after /仅当theme.carbonAds存在时v-if才渲染广告容器主题提供了aside-ads-before与aside-ads-after两个插槽允许在广告位上下插入自定义内容与VPDocAsideSponsors赞助商模块共享侧边栏底部区域样式上通过.spacer .VPDocAsideCarbonAds等选择器保持间距协调。八、样式定制用 CSS 变量对齐站点视觉广告区域由 VPCarbonAds.vue 的 scoped 样式渲染容器为圆角卡片border-radius: 0.75rem最小高度 16rem内容居中字体 0.75rem。其颜色全部通过 CSS 变量驱动定义在 vars.css--vp-carbon-ads-text-color: var(--vp-c-text-1); --vp-carbon-ads-poweredby-color: var(--vp-c-text-2); --vp-carbon-ads-bg-color: var(--vp-c-bg-soft); --vp-carbon-ads-hover-text-color: var(--vp-c-brand-1); --vp-carbon-ads-hover-poweredby-color: var(--vp-c-text-1);默认值自动跟随主题的明暗配色系统。如需自定义可在站点全局样式中覆盖:root { --vp-carbon-ads-bg-color: #f6f6f7; --vp-carbon-ads-text-color: #333; }此外组件通过:deep()对 Carbon 注入的 DOM 结构做了样式归一化广告图片居中圆角、.carbon-text链接文字上下留白、.carbon-poweredby以大写字母小字号展示且只显示第一个注入的广告块.VPCarbonAds :deep( div:first-of-type)保证布局稳定。九、注意事项与常见问题凭证获取code与placement需要在 Carbon Ads 平台注册站点并创建广告位后获得平台会为每个广告位分配唯一的 serve 与 placement 标识移动端不可见是设计行为由于min-width: 80rem的媒体查询门槛手机端不会展示广告位这是刻意为之的节流策略而非 bug广告加载失败不影响页面脚本采用异步注入即使 CDN 不可达容器内只会留下空白卡片背景不会阻塞文档渲染与赞助商模块的关系若同时配置了VPDocAsideSponsors广告位默认渲染在赞助商区块之后两者可在侧边栏共存。十、参考文件索引配置入口docs/config.ts各语言版本配置示例见docs/en/config.ts、docs/zh/config.ts等类型定义types/default-theme.d.tsCarbonAdsOptions、types/default-theme.d.tsThemeConfig.carbonAds组件实现src/client/theme-default/components/VPCarbonAds.vue、src/client/theme-default/components/VPDocAsideCarbonAds.vue挂载位置src/client/theme-default/components/VPDocAside.vue编译期标志src/node/plugin.ts样式变量src/client/theme-default/styles/vars.css【免费下载链接】vitepressVite Vue powered static site generator.项目地址: https://gitcode.com/gh_mirrors/vi/vitepress创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考