AstroPaper 集成指南

关于 AstroPaper

AstroPaper 是一个极简、响应式、无障碍且 SEO 友好的 Astro 博客主题。它基于现代 Web 技术栈构建，提供了出色的性能和用户体验。

主要特性

• 🚀 超快性能: 基于 Astro 框架，提供极致的加载速度
• 📱 响应式设计: 完美适配从移动设备到桌面的各种屏幕
• ♿ 无障碍支持: 支持键盘导航和屏幕阅读器
• 🔍 SEO 优化: 内置 SEO 最佳实践，提升搜索引擎排名
• 🌙 深色模式: 支持明暗主题切换
• 🔎 模糊搜索: 内置快速搜索功能
• 📄 类型安全: 完整的 TypeScript 支持
• 🎨 高度可定制: 灵活的配置选项和样式定制

技术栈

• 框架: Astro
• 样式: TailwindCSS
• 类型检查: TypeScript
• 图标: Tabler Icons
• 搜索: FuseJS
• 代码格式化: Prettier
• 代码检查: ESLint

本指南基于成功集成 AstroPaper 博客主题到现有项目的实践经验，记录了所有关键步骤和常见问题的解决方案。

项目概述

目标: 将 AstroPaper 博客主题集成到现有的 React 项目中，实现主站点和博客的统一部署。

最终效果:

• 主站点: https://yoursite.com
• 博客: https://yoursite.com/blog

1. 项目结构设置

1.1 目录结构

your-project/
├── src/                    # 主项目源码
├── public/                 # 主项目静态资源
├── blog/                   # AstroPaper 博客项目
│   ├── src/
│   ├── public/
│   ├── package.json
│   └── astro.config.ts
├── package.json            # 主项目配置
├── vercel.json            # Vercel 部署配置
└── .gitignore

1.2 创建博客目录

# 在项目根目录下创建 blog 目录
mkdir blog
cd blog

# 使用 AstroPaper 模板初始化
npx create-astro@latest . --template satnaing/astro-paper

2. AstroPaper 配置

2.1 修改 astro.config.ts

import { defineConfig } from "astro/config";
import tailwindcss from "@tailwindcss/vite";
import sitemap from "@astrojs/sitemap";
// ... 其他导入

export default defineConfig({
  site: "https://yoursite.com",
  base: "/blog",  // 关键配置：设置基础路径
  integrations: [
    sitemap({
      filter: page => SITE.showArchives || !page.endsWith("/archives"),
    }),
  ],
  // ... 其他配置
});

2.2 更新博客配置文件

编辑 blog/src/config.ts:

export const SITE = {
  website: "https://yoursite.com/blog/",
  author: "Your Name",
  desc: "Your blog description",
  title: "Your Blog Title",
  // ... 其他配置
};

3. 主项目集成

3.1 添加博客路由 (React 项目)

创建 src/pages/Blog.tsx:

import { useEffect } from 'react';

const Blog = () => {
  useEffect(() => {
    // 开发环境重定向到本地博客服务器
    if (import.meta.env.DEV) {
      window.location.href = 'http://localhost:4321/blog/';
    } else {
      // 生产环境重定向到博客路径
      window.location.href = '/blog/';
    }
  }, []);

  return (
    <div className="flex items-center justify-center min-h-screen">
      <div className="text-center">
        <p className="mb-4">正在跳转到博客...</p>
        <a href="/blog/" className="text-blue-500 hover:underline">
          点击这里手动跳转
        </a>
      </div>
    </div>
  );
};

export default Blog;

3.2 添加导航链接

在主项目的导航组件中添加博客链接:

<a href="/blog" className="nav-link">
  博客
</a>

4. Vercel 部署配置

4.1 创建 vercel.json

{
  "buildCommand": "pnpm run build && cd blog && pnpm install && pnpm run build && cd .. && mkdir -p dist/blog && cp -r blog/dist/* dist/blog/",
  "outputDirectory": "dist",
  "installCommand": "pnpm install",
  "rewrites": [
    {
      "source": "/blog/(.*)",
      "destination": "/blog/$1"
    },
    {
      "source": "/blog",
      "destination": "/blog/index.html"
    }
  ],
  "cleanUrls": true,
  "trailingSlash": false
}

4.2 构建命令说明

• pnpm run build: 构建主项目
• cd blog && pnpm install && pnpm run build: 进入博客目录，安装依赖并构建
• mkdir -p dist/blog && cp -r blog/dist/* dist/blog/: 将博客构建结果复制到主项目的输出目录

5. Git 仓库管理

5.1 配置 .gitignore

# 主项目
node_modules
dist
*.local

# 博客项目
blog/node_modules/
blog/dist/
blog/.astro/
blog/.vercel/
blog/.netlify/
blog/.env*

# Vercel
.vercel

5.2 重要提醒：避免 Git 子模块

⚠️ 关键问题: 不要将 blog 目录设置为 Git 子模块，这会导致 Vercel 部署失败。

如果意外创建了子模块，需要删除:

# 删除子模块配置
rm -rf blog/.git
git rm --cached blog

# 重新添加为普通目录
git add blog/
git commit -m "Convert blog from submodule to regular directory"

6. 本地开发环境

6.1 启动开发服务器

需要同时运行两个开发服务器:

# 终端 1: 启动主项目
npm run dev  # 通常在 http://localhost:8080

# 终端 2: 启动博客项目
cd blog
pnpm dev     # 通常在 http://localhost:4321

6.2 本地访问

• 主站点: http://localhost:8080
• 博客: http://localhost:4321/blog
• 从主站点跳转: http://localhost:8080/blog → 自动重定向到 http://localhost:4321/blog

7. 常见问题和解决方案

7.1 Vercel 部署失败：找不到 blog/package.json

问题: ERR_PNPM_NO_PKG_MANIFEST No package.json found in /vercel/path0/blog

原因: blog 目录被设置为 Git 子模块，Vercel 无法访问子模块内容。

解决方案:

1. 删除 blog 目录的 .git 文件夹
2. 将 blog 目录作为普通目录提交到主仓库
3. 确保 blog 目录下的所有文件都正确提交

7.2 博客页面 404 错误

问题: 访问 /blog 返回 404

可能原因和解决方案:

1. astro.config.ts 中 base 路径未设置: 确保设置 base: "/blog"
2. Vercel 路由配置错误: 检查 vercel.json 中的 rewrites 配置
3. 构建输出目录错误: 确保博客文件正确复制到 dist/blog/ 目录

7.3 本地开发时博客链接无法访问

问题: 点击博客链接后页面无法加载

解决方案:

1. 确保博客开发服务器正在运行 (cd blog && pnpm dev)
2. 检查 Blog.tsx 组件中的重定向逻辑
3. 确认端口号是否正确 (默认 4321)

7.4 样式或资源加载失败

问题: 博客页面样式丢失或图片无法显示

解决方案:

1. 检查 astro.config.ts 中的 base 配置
2. 确保所有资源路径都是相对于 /blog/ 的
3. 检查 Vercel 的静态资源配置

8. 部署验证清单

部署完成后，请验证以下功能:

• 主站点正常访问
• 博客首页正常访问 (/blog)
• 博客文章页面正常访问
• 博客导航和链接正常工作
• 样式和图片正常加载
• RSS 订阅功能正常
• 搜索功能正常 (如果启用)

9. 常见问题修复

9.1 本地开发时URL跳转问题

问题描述: 在本地开发环境中，博客内的所有链接都没有加上 /blog 前缀，导致跳转到错误的URL（如跳转到主域名而不是博客页面）。

根本原因: AstroPaper组件中的链接使用了绝对路径（如 href="/"、href="/posts"），没有考虑到 astro.config.ts 中设置的 base: "/blog" 配置。

解决方案: 修改所有组件中的绝对路径链接，使用 import.meta.env.BASE_URL 来动态构建正确的URL路径。

需要修复的文件:

1. blog/src/components/Header.astro - 导航菜单中的所有链接
2. blog/src/components/Tag.astro - 标签链接
3. blog/src/components/BackButton.astro - 返回按钮链接

修复示例:

<!-- 修复前 -->
<a href="/posts">Posts</a>
<a href="/tags">Tags</a>
<a href="/">Home</a>

<!-- 修复后 -->
<a href={`${import.meta.env.BASE_URL}/posts`}>Posts</a>
<a href={`${import.meta.env.BASE_URL}/tags`}>Tags</a>
<a href={`${import.meta.env.BASE_URL}/`}>Home</a>

验证方法: 启动本地开发服务器后，确保所有博客内的链接都正确跳转到 /blog 路径下的页面。

10. 性能优化建议

1. 启用 Vercel 缓存: 配置适当的缓存策略
2. 图片优化: 使用 Astro 的图片优化功能
3. 代码分割: 确保主项目和博客的代码独立加载
4. CDN 配置: 利用 Vercel 的全球 CDN

11. 总结

通过以上步骤，你可以成功将 AstroPaper 博客主题集成到现有项目中。关键要点:

1. 正确设置 base 路径: astro.config.ts 中的 base: "/blog"
2. 避免 Git 子模块: 将 blog 作为普通目录管理
3. 配置 Vercel 多项目构建: 使用组合构建命令
4. 本地开发双服务器: 同时运行主项目和博客服务器

遵循这个指南，你应该能够在其他项目中一次性成功集成 AstroPaper 博客主题。