npm package: @ourines/seo-dev-buddy
Description: A framework-agnostic SEO diagnostic plugin for development stage, following Google Search best practices
Author: ourines
Latest version: 1.0.1

# SEO Dev Buddy

一个框架无关的 SEO 诊断插件，专为开发阶段设计，遵循 Google Search 最佳实践。

## 特性

- 🔍 **实时 SEO 分析** - 在开发过程中实时检测 SEO 问题
- 🎯 **Google 最佳实践** - 基于 Google Search 官方指南
- 🚀 **React 支持** - 完整的 React 组件和 Hook 支持
- 📱 **响应式界面** - 美观的浮动面板，不影响开发体验
- ⚡ **零配置** - 开箱即用，自动检测页面 SEO 元素
- 🎨 **内联样式** - 无需外部 CSS 依赖，避免样式冲突

## 安装

```bash
npm install @ourines/seo-dev-buddy
# 或
yarn add @ourines/seo-dev-buddy
# 或
pnpm add @ourines/seo-dev-buddy
```

## 快速开始

### React 应用

```tsx
import { SeoDevBuddy } from '@ourines/seo-dev-buddy';

function App() {
  return (
    <div>
      {/* 你的应用内容 */}
      <h1>我的网站</h1>
      <p>网站内容...</p>
      
      {/* SEO Dev Buddy 组件 - 仅在开发环境显示 */}
      {process.env.NODE_ENV === 'development' && <SeoDevBuddy />}
    </div>
  );
}
```

### Astro 应用

```astro
---
// src/components/SeoDevBuddy.astro
import { SeoDevBuddy } from '@ourines/seo-dev-buddy';
---

<!-- 在页面底部添加 -->
<SeoDevBuddy client:load />
```

### 其他框架

SEO Dev Buddy 是一个 React 组件，但可以通过以下方式在其他框架中使用：

1. **作为独立的微前端组件**
2. **通过 iframe 嵌入**
3. **使用 Web Components 包装器**（计划中）

## 功能特性

### 实时 SEO 检查

SEO Dev Buddy 会自动检查以下 SEO 要素：

#### 基础要素

- ✅ **Title 标签** - 检查存在性和长度 (30-60 字符)
- ✅ **Meta Description** - 检查存在性和长度 (120-160 字符)
- ✅ **H1 标签** - 检查数量和内容
- ✅ **Canonical URL** - 检查规范链接设置
- ✅ **Meta Robots** - 检查爬虫指令
- ✅ **HTML Lang** - 检查语言声明

#### 内容和可访问性

- ✅ **图片 Alt 属性** - 统计缺失的 alt 文本
- ✅ **标题结构** - 检查 H2-H6 标签层级
- ✅ **内部链接** - 统计站内链接数量
- ✅ **外部链接** - 统计站外链接数量
- ✅ **字数统计** - 检查页面内容长度

#### Open Graph

- ✅ **OG Title** - 社交媒体标题
- ✅ **OG Description** - 社交媒体描述
- ✅ **OG Image** - 社交媒体图片
- ✅ **OG URL** - 规范 URL
- ✅ **OG Type** - 内容类型

#### Twitter Cards

- ✅ **Twitter Card** - 卡片类型
- ✅ **Twitter Title** - Twitter 标题
- ✅ **Twitter Description** - Twitter 描述
- ✅ **Twitter Image** - Twitter 图片

#### 技术 SEO

- ✅ **Viewport Meta** - 移动端适配
- ✅ **结构化数据** - JSON-LD 检测
- ✅ **发布日期** - 文章发布时间

### 数据导出

- 📊 **JSON 导出** - 一键复制所有 SEO 数据
- 📈 **状态指示** - 错误、警告、成功状态
- 🔍 **详细说明** - 每个检查项的详细解释

## API 参考

### 主要组件

```tsx
import { SeoDevBuddy } from '@ourines/seo-dev-buddy';

// 基本使用
<SeoDevBuddy />
```

### 类型定义

```tsx
// SEO 检查结果
interface SEOCheckResult {
  id: string;
  label: string;
  category: 'essentials' | 'content' | 'social' | 'technical';
  status: 'error' | 'warning' | 'success';
  value: any;
  displayValue: string;
  description: string;
  recommendation: string;
  isCritical: boolean;
}

// SEO 报告
interface SEOReport {
  checks: SEOCheckResult[];
  score: number;
  timestamp: string;
}
```

## 开发

```bash
# 克隆仓库
git clone https://github.com/ourines/seo-dev-buddy.git
cd seo-dev-buddy

# 安装依赖
pnpm install

# 开发模式
pnpm dev

# 构建
pnpm build

# 测试
pnpm test

# 类型检查
pnpm type-check
```

## 路线图

- [ ] Vue 3 支持
- [ ] Angular 支持
- [ ] Web Components 版本
- [ ] 自定义规则配置
- [ ] 性能检查
- [ ] 可访问性检查
- [ ] 多语言支持

## 贡献

欢迎提交 Issue 和 Pull Request！

## 许可证

MIT License

## 更新日志

查看 [CHANGELOG.md](./CHANGELOG.md) 了解版本更新详情。

---

## 未来增强计划

- **优化状态检查**:
  - 为 OG/Twitter 描述添加长度检查（少于 100 字符时警告）
  - 检查 Canonical URL 是否为绝对路径
  - 警告图片 URL 中的双斜杠（`//`）问题

- **改进代码结构**:
  - 重构 `getItemStatusLevel` 为更小、更专注的函数
  - 创建辅助函数避免重复的 `seoData` 检索逻辑

- **功能增强**:
  - 基础关键词分析（需要用户输入目标关键词）
  - 显示基础性能指标（如 LCP）使用 `window.performance`
  - 尝试基础 JSON-LD 验证或链接到外部验证器
  - 添加警告阈值配置选项（如字数统计）