AstroPaper主题添加Waline评论

记录为 Astro Paper 主题集成 Waline 评论系统的完整步骤。

Table of contents

步骤 1：部署 Waline 服务端

访问：部署Waline服务端

步骤 2：注册管理员账号

部署完成后，访问 https://waline.yourdomain.com/ui，注册第一个账号，这个账号会自动成为管理员，可以登录管理后台审核评论、查看数据统计。

步骤 3：集成到 Astro paper

（1）安装 Waline 客户端

npm install @waline/client

（2）创建 Waline 组件

---

---

<div id="waline"></div>

<script>
  import { init, type WalineInstance } from "@waline/client";
  import "@waline/client/waline.css";
  import { any } from "astro:schema";

  function loadWaline() {
    const walineInstance = init({
      el: "#waline",
      serverURL: "https://xxx.xxx.com", // 改成你的Waline域名
      path: window.location.pathname,
      lang: "zh-CN",
      dark: 'html[data-theme="dark"]', // 自动适配暗色模式
      imageUploader: false, // 关闭图片上传功能
      login: "disable", // 禁止第三方登录
      search: false, // 关闭表情包搜索
      emoji: [
        "//unpkg.com/@waline/emojis@latest/weibo",
        "//unpkg.com/@waline/emojis@latest/bilibili",
      ],
      meta: ["nick", "mail"],
      requiredMeta: ["nick"], // 设置昵称必填
      pageSize: 10,
    });

    return walineInstance;
  }

  // 存储实例，方便页面切换时销毁
  /** @type {import('@waline/client').WalineInstance | null} */
  let walineInstance: WalineInstance | null = null;

  // 页面首次加载
  if (document.readyState === "loading") {
    document.addEventListener("DOMContentLoaded", () => {
      walineInstance = loadWaline();
    });
  } else {
    walineInstance = loadWaline();
  }

  // 【关键】视图过渡路由兼容
  document.addEventListener("astro:page-load", () => {
    if (walineInstance && walineInstance.destroy) {
      walineInstance.destroy();
    }
    walineInstance = loadWaline();
  });
</script>

<style>
  #waline {
    margin-top: 2rem;
  }
</style>src/components/Waline.astro

步骤 4：在文章中引入组件

</article>
<!-- 评论区 -->
<Waline />
<hr class="my-8 border-dashed" />src/layouts/PostDetails.astro

常见问题

1. 注册管理员账号时提示：403 Forbidden

• 原因：环境变量 SECURE_DOMAINS 或 SITE_URL 配置不正确
• 解决方案：确保两个变量都正确填写，注意多个域名用英文逗号分隔

2. 生产环境（npm run build 后）无法提交评论

• 原因：同上，生产环境下的域名校验更严格
• 解决方案：检查 Waline 服务端的环境变量配置，确保博客域名和 Waline 域名都已加入白名单

3. 暗色模式不生效

• 原因：Astro Paper 默认使用 html[data-theme="dark"]，直接使用 dark: "auto" 不生效
• 解决方案：修改配置为 dark: 'html[data-theme="dark"]'