Carbon Ads 集成

Carbon Ads 是一个面向开发者社区的优质广告平台，适合技术类文档站点。本文档介绍如何在 VitePress 中集成 Carbon Ads。

什么是 Carbon Ads

Carbon Ads 的特点：

• 开发者友好：广告内容与开发者相关
• 非侵入式：简洁的广告样式
• 高收益：技术受众价值高
• 易集成：简单的配置流程

快速开始

1. 注册账号

1. 访问 Carbon Ads 官网
2. 提交站点申请
3. 等待审核通过（通常需要几天）

2. 获取配置信息

审核通过后，获取以下信息：

• carbon - 你的发布商 ID
• custom - 自定义配置（可选）
• placement - 广告位置标识

配置方式

默认主题集成

VitePress 默认主题内置了 Carbon Ads 支持：

// docs/.vitepress/config.mts
export default defineConfig({
  themeConfig: {
    carbonAds: {
      code: 'your-carbon-code',
      placement: 'your-placement-id'
    }
  }
})

完整配置选项

export default defineConfig({
  themeConfig: {
    carbonAds: {
      code: 'CEBICK3I',           // 必填：发布商代码
      placement: 'vitepressdev',   // 必填：广告位置
      custom: 'your-custom-data',  // 可选：自定义数据
      format: 'carbon-responsive', // 可选：广告格式
      fallback: 'fallback-code'    // 可选：备用广告代码
    }
  }
})

自定义广告位置

添加到页面特定位置

如果需要更多控制，可以自定义广告位置：

<!-- docs/.vitepress/theme/components/CustomCarbonAds.vue -->
<script setup>
import { onMounted, ref } from 'vue'

const props = defineProps({
  code: String,
  placement: String
})

const containerRef = ref(null)

onMounted(() => {
  if (!containerRef.value) return
  
  // 创建 script 元素
  const script = document.createElement('script')
  script.src = '//cdn.carbonads.com/carbon.js'
  script.setAttribute('serve', props.code)
  script.setAttribute('placement', props.placement)
  script.setAttribute('id', 'carbon-script')
  script.async = true
  
  containerRef.value.appendChild(script)
})
</script>

<template>
  <div ref="containerRef" class="carbon-ads-container">
    <div id="carbon-block"></div>
  </div>
</template>

<style>
.carbon-ads-container {
  margin: 1rem 0;
  min-height: 100px;
}

.carbon-ads-container:empty::after {
  content: '广告加载中...';
  color: var(--vp-c-text-3);
}
</style>

在布局中使用

// docs/.vitepress/theme/index.ts
import DefaultTheme from 'vitepress/theme'
import { h } from 'vue'
import CustomCarbonAds from './components/CustomCarbonAds.vue'

export default {
  extends: DefaultTheme,
  Layout: () => h(DefaultTheme.Layout, null, {
    // 在侧边栏底部显示广告
    'sidebar-bottom': () => h(CustomCarbonAds, {
      code: 'your-code',
      placement: 'your-placement'
    }),
    // 在文档底部显示广告
    'doc-after': () => h(CustomCarbonAds, {
      code: 'your-code',
      placement: 'your-placement'
    })
  })
}

样式自定义

覆盖默认样式

/* docs/.vitepress/theme/custom.css */

/* Carbon Ads 容器 */
.carbon-wrap {
  margin: 1rem 0;
  padding: 1rem;
  border: 1px solid var(--vp-c-divider);
  border-radius: 8px;
  background: var(--vp-c-bg-soft);
}

/* 广告图片 */
.carbon-img {
  float: left;
  margin-right: 1rem;
}

.carbon-img img {
  border-radius: 4px;
}

/* 广告文字 */
.carbon-text {
  color: var(--vp-c-text-2);
  font-size: 0.875rem;
}

/* 广告链接 */
.carbon-text:hover {
  color: var(--vp-c-brand-1);
}

/* Carbon 标识 */
.carbon-poweredby {
  display: block;
  margin-top: 0.5rem;
  font-size: 0.75rem;
  color: var(--vp-c-text-3);
}

深色模式适配

/* 深色模式下的样式调整 */
html.dark .carbon-wrap {
  background: var(--vp-c-bg-alt);
  border-color: var(--vp-c-divider-light);
}

html.dark .carbon-text {
  color: var(--vp-c-text-1);
}

响应式设计

/* 移动端适配 */
@media (max-width: 768px) {
  .carbon-wrap {
    padding: 0.75rem;
  }
  
  .carbon-img {
    float: none;
    margin: 0 0 0.5rem 0;
    text-align: center;
  }
  
  .carbon-img img {
    max-width: 100%;
    height: auto;
  }
}

道德广告政策

确保用户体验

1. 不要过度投放

   • 每页最多一个广告
   • 避免弹窗式广告

2. 保持内容质量

   • 广告不应干扰阅读
   • 内容价值高于广告

3. 遵守政策

   • 不要点击自己的广告
   • 不要要求他人点击

广告屏蔽检测

<script setup>
import { ref, onMounted } from 'vue'

const adBlocked = ref(false)

onMounted(() => {
  // 检测广告是否被屏蔽
  setTimeout(() => {
    const ad = document.querySelector('.carbon-wrap')
    if (!ad || ad.offsetHeight === 0) {
      adBlocked.value = true
    }
  }, 2000)
})
</script>

<template>
  <div class="carbon-wrap" v-if="!adBlocked">
    <!-- Carbon Ads 代码 -->
  </div>
  <div v-else class="support-notice">
    <p>感谢您的支持！如果可以，请将本站加入广告屏蔽白名单。</p>
  </div>
</template>

收益优化

位置优化

最佳广告位置：

1. 侧边栏顶部 - 可见度高
2. 文章末尾 - 阅读完成后
3. 页面顶部 - 首屏可见

流量优化

1. SEO 优化 - 提高搜索流量
2. 内容质量 - 吸引忠实读者
3. 定期更新 - 保持活跃度

替代方案

如果 Carbon Ads 不适合，可以考虑：

1. BuyMeACoffee

<script setup>
const link = 'https://buymeacoffee.com/yourname'
</script>

<template>
  <a :href="link" target="_blank" class="bmc-button">
    <img src="https://cdn.buymeacoffee.com/buttons/bmc-new-btn-logo.svg" alt="Buy me a coffee">
    <span>请我喝杯咖啡</span>
  </a>
</template>

<style>
.bmc-button {
  display: inline-flex;
  align-items: center;
  gap: 8px;
  padding: 8px 16px;
  background: #FFDD00;
  border-radius: 8px;
  text-decoration: none;
  color: #000;
}
</style>

2. Ko-fi

<template>
  <a href="https://ko-fi.com/yourname" target="_blank" class="kofi-button">
    支持作者
  </a>
</template>

3. Patreon

<template>
  <a href="https://patreon.com/yourname" target="_blank" class="patreon-button">
    成为赞助者
  </a>
</template>

常见问题

广告不显示

检查以下项目：

1. 代码和 placement 是否正确
2. 域名是否已验证
3. 浏览器是否屏蔽了广告

收益过低

可能的原因：

1. 流量不足
2. 受众不匹配
3. 广告位置不佳

样式问题

确保 CSS 正确加载：

export default defineConfig({
  head: [
    ['link', { rel: 'stylesheet', href: '/custom.css' }]
  ]
})

相关资源

• Carbon Ads 官方文档
• VitePress 默认主题配置
• 评论系统集成

下一步

了解 插件开发指南 扩展更多功能。