🚀 AstroPaper 主题优化 TODO 清单

最后更新：2026-03-24
状态：持续维护中 ✨

本文档汇总了 AstroPaper 主题的各项优化建议和待办事项，旨在持续提升博客的性能、用户体验和开发效率。

📋 核心优化项目

🔒 内容集合与目录管理优化 ✅ 已完成

问题描述
主题自带的 _examples、_releases 目录和用户创建的 _templates 目录被 Astro 内容集合系统误处理，导致构建错误。

解决方案
✅ 已在 src/content.config.ts 中更新 glob 模式： “typescript pattern: [ ”/[^_]*.md”, // 用户原创内容 ”!_templates/”, // 排除模板 ”!_examples/”, // 排除示例 ”!_releases/” // 排除发布说明 ]

**效果**  
- 构建稳定性提升 💪
- 错误预防能力增强 🛡️
- 内容管理更加清晰 📂

---

### 🌐 资源路径引用优化 ⏳ 待实施

**问题描述**  
当前使用相对路径引用静态资源（如 `ogImage`），容易因目录层级计算错误导致 `ImageNotFound` 错误。

**推荐方案**  
🔧 **采用 `@/` 别名路径**：
``yaml
# 当前（易出错）
ogImage: ../../../assets/images/example.png

# 推荐（稳定可靠）
ogImage: @/assets/images/example.png

实施步骤

• 确认 Astro 配置支持 @/ 别名
• 批量更新现有文章的 ogImage 路径
• 更新 Obsidian 模板中的路径格式
• 文档化路径使用规范

预期收益

• 彻底解决路径层级计算问题 🎯
• 提升开发体验和代码可读性 👓
• 减少构建错误率 📉

📅 日期格式自动化优化 ⏳ 待实施

问题描述
Obsidian Templater 生成的日期占位符需要手动配置为 ISO 8601 格式，存在配置遗漏风险。

推荐方案
🔧 创建标准化 Templater 模板函数：

// 在Templater用户脚本中创建
tp.user.generateBlogFrontmatter = async (title, author, tags, description) => {
  const now = tp.date.now("YYYY-MM-DDTHH:mm:ss") + "Z";
  const slug = title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
  
  return `---
title: "${title}"
author: "${author}"
pubDatetime: ${now}
modDatetime: ${now}
slug: "${slug}"
featured: false
draft: true
tags:
  - ${tags}
description: "${description}"
---`;
};

实施步骤

• 创建 Templater 用户脚本函数
• 更新博客模板调用新函数
• 测试日期格式兼容性
• 文档化使用方法

预期收益

• 100% 确保日期格式正确 ✅
• 自动化 slug 生成 🤖
• 减少手动配置错误 📝

🎨 导航菜单样式增强 ⏳ 待实施

当前状态
已实现基础的 .active-nav 样式，但仍有优化空间。

推荐方案
🔧 添加过渡动画和主题适配：

“css .active-nav { @apply text-accent underline decoration-solid decoration-1 underline-offset-8; transition: all 0.3s ease-in-out; }

/* 深色主题微调 */ html[data-theme=“dark”] .active-nav { text-shadow: 0 0 8px rgba(255, 107, 1, 0.3); }

**实施步骤**
- [ ] 添加 CSS 过渡效果
- [ ] 优化深色主题下的视觉效果
- [ ] 测试不同设备上的显示效果
- [ ] 收集用户反馈进行调整

**预期收益**  
- 提升用户交互体验 ✨
- 增强视觉层次感 🎭
- 保持主题一致性 🎨

---

### 🔗 外部链接安全增强 ⏳ 待实施

**当前状态**  
分享链接已添加 `target="_blank" rel="noopener noreferrer"`，但其他外部链接可能遗漏。

**推荐方案**  
🔧 **全局外部链接处理器**：

``astro
<!-- 创建 Link 组件 -->
<a 
  href={href}
  target={isExternal ? "_blank" : undefined}
  rel={isExternal ? "noopener noreferrer" : undefined}
  class={className}
>
  <slot />
</a>

实施步骤

• 创建通用 Link 组件
• 替换所有外部链接使用新组件
• 添加自动检测外部链接逻辑
• 确保 SEO 友好性不受影响

预期收益

• 全站外部链接安全统一 🔒
• 开发效率提升（减少重复代码）⚡
• 安全性全面保障 🛡️

📊 优化优先级矩阵

🎯 实施路线图

第一阶段：稳定性提升（1-2周）

• 内容集合目录排除 ✅
• 资源路径引用优化
• 日期格式自动化

第二阶段：用户体验优化（2-4周）

• 导航菜单样式增强
• 外部链接安全增强
• 性能监控和 Lighthouse 评分优化

第三阶段：高级功能（1-2个月）

• 搜索功能增强
• PWA 支持
• Analytics 集成

💡 提示：每个优化项目实施前，请务必在本地运行 pnpm run build 进行完整验证，确保不会引入新的构建问题。

本文档将持续更新，欢迎提出更多优化建议！