AstroPaper主题添加Waline评论 | Donghai

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

Open Table of contents

步骤 1：部署 Waline 服务端
步骤 2：注册管理员账号
步骤 3：集成到 Astro paper
步骤 4：在文章中引入组件
常见问题

步骤 1：部署 Waline 服务端

步骤 2：注册管理员账号

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

NOTE

如果点击“注册”提示：403 Forbidden 错误，请检查 SECURE_DOMAINS、SITE_URL 环境变量。例如我的博客地址是 mysite.com，Waline评论地址是 waline.mysite.com，那么这两个环境变量应该这样填写：SECURE_DOMAINS=mysite.com,comments.mysite.com，SITE_URL=mysite.com

步骤 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：在文章中引入组件

比如我们把评论区放在“分享这篇文章：”下方：

<ShareLinks />

<!-- 评论区 -->
<Waline />

<hr class="my-6 border-dashed" />src/layouts/PostDetails.astro

常见问题

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

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

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

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

暗色模式不生效

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

（完）

如果这篇文章刚好帮到了你，欢迎请我喝杯咖啡！

推荐订阅源

Donghai's Blog