🌏 本站/博客部署+SEO 优化+测试样例，全流程打包教程

我选择 Notion 搭建博客，其实是出于一种平衡：

我希望写作流程尽可能轻便、界面美观、内容管理足够灵活，同时也不想花太多时间在复杂的前端框架上打转。Notion 配合静态生成工具（比如 Astro 或 Super），看起来是一个理想解。

Notion 在写作体验上的流畅感，让我坚持更新比以往任何一次都久；我也逐步建立起自己的知识分类体系，内容架构越来越清晰。这更像是一种“写给未来的准备”，而不是急功近利的内容发布。

一、先解码关键词 🔍

二、深层含义：Astro 的 Notion 集成本质是「快照模式」

sequenceDiagram
    participant 你的Notion
    participant Astro
    participant 用户
    你的Notion->>Astro: 1. 写作时：在Notion编辑内容
    Astro->>你的Notion: 2. 构建时：一次性拉取全部数据
    Astro->>Astro: 3. 生成静态HTML文件（像拍照定格）
    Astro->>用户: 4. 用户访问时：直接发送HTML文件

关键限制：

⚠️ 用户看到的永远是 构建时 的 Notion 内容快照

⚠️ 用户无法在网站上 实时交互（如评论/点赞）

⚠️ Notion 内容更新后需 重新构建部署 才能同步

三、对比其他模式就懂了 🆚

场景：你更新了 Notion 里的文章

💡 为什么 Astro 默认用 SSG？

为了 速度与性价比：

• 生成静态文件 → CDN 全球秒开
• 无需服务器 → 托管在 Vercel/Netlify 永久免费

四、Notion 集成的具体影响 ⚠️

你能轻松做到的 ✅：

• 把 Notion 当 无头CMS（内容管理系统）
• 自动生成博客/作品集/文档站
• 享受 极快的加载速度（页面已是成品）

你无法直接实现的 ❌：

• 用户在网站留言 → 实时保存回 Notion
• 显示 Notion 数据库的 实时更新数据
• 需要登录才能查看的 私有内容

五、突破限制的解决方案 🔨

1. 半自动化更新

# 用 GitHub Actions 设置每日自动构建
name: Update Notion Content
on:
  schedule:
    - cron: '0 0 * * *'  # 每天UTC 0点执行
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - run: npm run build
      - run: vercel deploy --prod

→ 用户每天看到的是 昨日 Notion 快照

2. 混合模式：SSG + 动态岛屿

---
// 静态生成主页面
import Counter from '../components/Counter.astro'
---
<!-- 在静态页面嵌入动态评论组件 -->
<Counter client:load />

→ 用 React/Vue 写交互部件，通过 client:load 激活

3. 接入 Serverless 服务

graph LR
    A[用户点击点赞] --> B(调用 Vercel Edge Function)
    B --> C{更新数据库}
    C --> D[Notion API]
    D --> E[返回结果到前端]

→ 通过 无服务器函数 中转动态操作

六、你的 Notion 网站最佳实践 ✨

1. 内容分层策略
   • 用 SSG 生成 核心展示页（作品集/博客）
   • 用动态组件实现 轻交互（点赞/订阅按钮）
2. 更新提示设计
   Copy

   <!-- 在页面顶部显示提示 -->
   <div class="update-alert">
     内容更新于：<span id="build-time">2024-07-25</span>
     <button onclick="location.reload()">检查更新</button>
   </div>
   

3. 拥抱 SSG 优势
   → 把网站部署在 Vercel
   → 开启 Incremental Static Regeneration 功能（增量更新）

七、总结：

「Astro集成方案仅支持SSG」=

你的 Notion 网站本质是「自动印刷机」：

• ✅ 高效生产精美手册
• ❌ 不能变成实时对讲机
• 🔧 但可通过 外挂设备 实现有限互动

后期可以做的：

1. 定制 SSG 优化方案（根据你的项目痛点）
2. 手写动态组件代码（评论/点赞功能）
3. 设计更新提示 UI（我身为设计师的专属优势） 👨💻

八、工具备忘

<script async src="https://pagead2.googlesyndication.com/pagead/js/adsbygoogle.js?client=ca-pub-9669713886681501"
     crossorigin="anonymous"></script>

我怎么给网站测速？

Security Verification

https://www.webpagetest.org

https://www.webpagetest.org/result/250706_YiDcSN_4K9/1/experiments/#Quick

dig www.ai233.top +short

# 使用 Invoke-WebRequest（别名 curl）
Invoke-WebRequest -Uri "https://www.ai233.top" -Method Head

# 或简化版（自动选择方法）
curl -Method Head "https://www.ai233.top"

# 使用系统原生工具，兼容性更好
cmd /c "curl -I https://www.ai233.top"

# 一键检查 CSP 并输出彩色结果
$response = Invoke-WebRequest -Uri "<https://www.ai233.top>" -Method Head
if ($response.Headers["Content-Security-Policy"]) {
    Write-Host "✅ CSP 已配置: " -ForegroundColor Green
    $response.Headers["Content-Security-Policy"]
} else {
    Write-Host "❌ 缺少 CSP 头" -ForegroundColor Red
}

九、安装

1.　Vercel CLI 全局命令的使用

• 确保安装Node.js
• 下载并安装适用于操作系统的 Node.js 和 npm：https://nodejs.org/
• 确认安装成功，可以通过在终端运行 node -v 和 npm -v 命令来检查版本号。

我不是很推荐安装特别新的版本，因为可能会导致一些不兼容，18.20.8 LTS 是我安装的，TS 是稳定版本的缩写，代表 Long Term Support。Node.js® 的 LTS 版本提供长期的维护和支持，通常包含重要的安全更新和关键修复，但不会引入新的功能。LTS 版本适合需要长期稳定运行的 Node.js 应用程序。

２.　重新安装Vercel CLI

如果换到另一台电脑上工作，需要重新安装Vercel CLI。Vercel CLI是一个全局工具，需要在使用它的每台计算机上单独安装。

从终端输出可以看到，您之前尝试运行vercel --version命令时收到了错误消息，表明Vercel CLI尚未安装。然后您成功运行了npm install -g vercel命令来安装它，安装完成后您能够使用vercel命令进行部署。

３．执行以下步骤：

1. 确保新电脑上已安装Node.js和npm
2. 运行npm install -g vercel命令安装Vercel CLI
3. 运行vercel login命令登录您的Vercel账户
4. 然后您就可以使用vercel命令部署您的项目了

安装完成后，您可以使用vercel --version命令验证安装是否成功。如果您想直接部署到生产环境，可以使用vercel --prod命令。

需要注意的是，Vercel CLI的安装是全局的（使用了-g标志），这意味着它会在您的用户目录下安装，而不是在项目目录中。这就是为什么您需要在每台新电脑上重新安装它。

４.　Github后台的设置

在代码不变的情况下，通过定时部署来拉取 Notion 中的最新内容更新博客。这不是冲突而是必要的补充机制。

感谢Kindly给我的思路，部署notion的一些后台设置

graph LR
    A[Notion 内容更新] --> B{GitHub Actions}
    B -->|定时触发| C[调用 Vercel Hook]
    C --> D[Vercel 重新构建]
    D --> E[拉取最新 Notion 数据]
    E --> F[生成新静态页面]
    
    G[代码更新] --> H[Vercel 自动部署]
    H --> F

到这里我以为设置完了，但其实还没有，需要在vercel项目的设置里，同样创建hook，填入main后点create

可以把 GitHub Secrets 里的 NOTION_API_SECRET、DATABASE_ID、CUSTOM_DOMAIN 等删掉，只保留 DEPLOY_HOOK_URL（除非你有其它 workflow 用到）

👇生成后有个网址，打开后返回内容：

✅ 返回内容解释

{
  "job": {
    "id": "XXXXXXXXXX",
    "state": "PENDING",
    "createdAt": 1750521279829
  }
}

astro-notion-blog-main/.github/workflows/deploy.yml at main · youxiaohanpian/astro-notion-blog-main

name: Deploy

on:
  schedule:
    - cron: '00 23 * * 1,3,5'  # UTC 每周一、三、五 23:00 → 北京时间每周二、四、六 7:00
  workflow_dispatch:

jobs:
  curl:
    name: Kick deploy hook
    runs-on: ubuntu-latest
    steps:
      - name: curl
        run: |
          curl -X POST \
          -H "Content-Type: application/json" \
          -d '{}' \
          '${{ secrets.DEPLOY_HOOK_URL }}'

🔄 代码增强

name: Notion Content Refresh

on:
  schedule:
    # 每天北京时间7点运行 (UTC 23:00)
    - cron: '00 23 * * *'
  workflow_dispatch:

jobs:
  refresh-content:
    runs-on: ubuntu-latest
    steps:
      - name: Check Secrets
        run: |
          if [ -z "${{ secrets.NOTION_REFRESH_HOOK }}" ]; then
            echo "❌ 错误：未检测到 NOTION_REFRESH_HOOK"
            exit 1
          fi

      - name: Trigger Content Refresh
        run: |
          # 发送部署请求
          curl -X POST "${{ secrets.NOTION_REFRESH_HOOK }}"
          
          echo "✅ 已触发内容刷新部署"
          
      - name: Verify Update
        timeout-minutes: 10
        run: |
          # 等待部署完成
          sleep 300
          
          # 检查最新文章更新时间
          LATEST_UPDATE=$(curl -s "https://api.notion.com/v1/databases/${{ secrets.NOTION_DATABASE_ID }}/query" \
            -H "Authorization: Bearer ${{ secrets.NOTION_API_KEY }}" \
            -H "Notion-Version: 2022-06-28" | jq -r '.results[0].last_edited_time')
          
          echo "最新内容更新时间: $LATEST_UPDATE"

🔄 部署后续会发生什么？

才点击打开这个 URL，就相当于“远程点了一下 Deploy 按钮”，Vercel 会立即开始重新构建并部署你的项目。

👉 去 Vercel 项目后台 → Deployments 页面

graph TD
  A[自定义域名] --> B{生效条件}
  B --> C1[DNS 解析正确]
  B --> C2[Vercel 项目已绑定]
  B --> C3[SSL 证书有效]

查看状态：

✅ 如果成功，会变成绿色的 "READY"

❌ 如果失败，会显示红色 "ERROR"，可以点击进去看详细日志

图片部署访问流程分析（国内用户）

创建缓存规则

graph LR
   用户[国内用户] --> Cloudflare[Cloudflare CDN节点]
    Cloudflare --> |① 首次请求| Vercel[Vercel服务器]
    Vercel --> |② 获取| Notion[Notion图片]
    Cloudflare --> |③ 缓存图片| 用户
   用户 --> |④ 后续请求| Cloudflare

📌 用法建议

你已经有这个 Deploy Hook 网址，以后可以：

✅ 方式一：手动触发部署

• 在浏览器里打开这个链接就能重新部署

✅ 方式二：自动触发（推荐）

• Notion 更新后自动调用：可以用 Zapier 或 IFTTT 来实现「当 Notion 新增页面 → 调用这个 Hook」
• 本地写脚本触发：比如加一个 deploy.sh 脚本自动 POST 请求这个 URL

Astro + Notion 博客的 SEO Checklist，

既包括基础配置，也包括进阶优化。也方便每次发布新文章或优化站点时快速检查 ✅

🌱 基础 SEO Checklist（发布就该具备）

📈 进阶优化 Checklist（加分项）

🧠 内容优化建议

🧰 工具推荐

十、博客本地测试用例 & 流程模板

确认 .env 里有正确的 NOTION_API_SECRET 和 DATABASE_ID

• 本地执行：

npm run build
npm run preview

build 生成静态文件，preview 本地起个静态服务器预览

1. 首页内容显示

• 打开首页（通常是 http://localhost:3000 或你的本地预览地址）
• 确认首页文章列表是否正常显示，文章标题、摘要、封面图加载正常
• 观察首页是否有明显的样式错乱

2. 首页 Tag 显示

• 首页是否正确显示 Tag 分类列表
• 点击不同 Tag，确认跳转到对应的 Tag 页面，文章列表正确过滤

3. 响应式测试

• 在浏览器切换不同屏幕尺寸（桌面、平板、手机）
• 检查页面布局是否自适应，元素没有重叠或溢出
• 交互按钮（分享、点赞）在不同尺寸下正常可用

4. Tag 页面分页和跳转

• 点击任意 Tag，确认页面跳转并显示该 Tag 下文章
• 如果文章数超过分页限制（比如 10 篇），测试分页按钮是否工作正常，内容正确切换

5. Notion文章漏写slug导致错误检测

• 人为制造一个测试文章，在 Notion 中故意删除或留空 slug
• 本地 build 时是否报错
• 访问该文章对应页面时，页面是否正确显示错误或跳转（避免白屏）

6. 日志列表页图片是否丢失

• 首页文章封面图和列表页缩略图是否全部正常加载
• 文章内容页内嵌的图片是否显示正常，没出现断链

7. 日志子页面字段显示正确性

• 进入任意一篇日志详情页
• 标题、日期、标签、内容、封面图是否正确展示
• 交互按钮（分享、点赞）功能是否正常
• 页脚上一篇/下一篇文章链接是否有效

额外推荐

• 错误捕获日志：留意终端是否有构建或运行时错误
• 网络请求：用浏览器开发者工具检查是否有资源请求失败
• SEO 预览：查看 meta 标签是否正确渲染

测试工具建议

• 用 Chrome DevTools 手动测试响应式
• 用 Postman 或 curl 测试某些接口（如果有）
• 将构建好的 dist 部署到临时环境验证线上表现（Vercel Preview 环境）
• 用 GitHub Action 集成简单的构建和部署自动化

后续考虑写一个简单的测试脚本（比如用 Puppeteer 或 Playwright 自动化浏览器跑一遍核心页面测试），适合后续持续集成用。写自动化测试脚本的基础模板，或者搭建 GitHub Action 自动跑这些测试