如何在 Astro 博客中优雅地实现全屏随机背景图

最近在折腾我的个人博客（基于 Astro 框架搭建）。原本的主题配置中只提供了一个顶部的静态 Banner 横幅，但我想要一个更具视觉冲击力的效果：一个每次刷新都能随机变换的全屏背景图。

经过一番摸索和踩坑，我最终采用了一种“前后端分离”的极客方案，不仅完美实现了效果，还顺手搭了一个属于自己的私人图库 API。这篇文章将记录整个全栈折腾的过程。

💡 为什么不直接改配置文件？#

博客自带的 config.ts 文件中虽然有 banner 的配置项，但它有两个局限：

只能填固定死的一张图片。
Astro 是静态生成的（SSG），配置文件的内容只在编译的那一瞬间生效，无法做到“每次访客刷新网页时动态计算随机数”。

为了突破这个限制，我们需要稍微“越界”，在博客的底层布局代码中引入客户端 JavaScript，并配合后端的动态 API 来实现。

🚀 第一步：搭建私人专属的随机图 API (后端)#

很多人会选择使用网上的免费随机图 API，但这往往会遇到 CORS（跨域拦截） 或 Mixed Content（HTTPS/HTTP 冲突） 的问题。

既然有自己的服务器，最优雅的方案当然是自己动手丰衣足食！

我在服务器（PHP 环境）上新建了一个站点 api.mydomain.com，并在根目录下建了一个 bg-images 文件夹用来存放收集来的高清壁纸。接着，写了一个只有十几行的极简 index.php 脚本：

1
<?php
2
// 允许跨域请求
3
header("Access-Control-Allow-Origin: *");
4

5
// 自动扫描 bg-images 文件夹下的所有图片文件
6
$image_folder = 'bg-images/';
7
$images = glob($image_folder . '*.{jpg,jpeg,png,gif,webp,avif}', GLOB_BRACE);
8

9
if (count($images) === 0) {
10
    die("未找到图片，请上传图片。");
11
}
12

13
// 随机抽取一张图片
14
$random_image = $images[array_rand($images)];
15

16
// 获取当前协议和域名
17
$protocol = (!empty($_SERVER['HTTPS']) && $_SERVER['HTTPS'] !== 'off' || $_SERVER['SERVER_PORT'] == 443) ? "https://" : "http://";
18
$domain = $_SERVER['HTTP_HOST'];
19

20
// 拼接完整 URL 并进行 302 重定向
21
$full_url = $protocol . $domain . '/' . $random_image;
22
header("Location: " . $full_url, true, 302);
23
exit;
24
?>

这个方案的绝妙之处在于：以后想更换或增加背景图，完全不需要动任何代码，只需要用 FTP 把图片丢进 bg-images 文件夹，API 就会自动识别并分发。

🎨 第二步：在博客中植入“魔法阵” (前端)#

有了 API 之后，我们就需要修改博客的主题布局文件了。在 Astro 项目中，找到类似于 src/layouts/Layout.astro 的全局布局文件。

滑动到页面最底部，在 </body> 标签的正上方，注入我们的自定义背景模块：

1
<div id="my-custom-bg"></div>
2

3
<style>
4
  #my-custom-bg {
5
    position: fixed;
6
    top: 0;
7
    left: 0;
8
    width: 100vw;
9
    height: 100vh;
10
    z-index: -1; /* 藏在最底层 */
11
    pointer-events: none; /* 防止遮挡页面上的点击事件 */
12
    background-size: cover;
13
    background-position: center;
14
    background-repeat: no-repeat;
15
    opacity: 0; /* 初始透明，准备淡入 */
16
    transition: opacity 0.8s ease-in-out; /* 丝滑的淡入动画 */
17

18
    /* 进阶质感：高斯模糊与防漏边 */
19
    filter: blur(3px);
20
    transform: scale(1.02);
21
  }
22

23
  #my-custom-bg.loaded {
24
    opacity: 0.6; /* 图片加载完成后的透明度 */
25
  }
26
</style>
27

28
<script is:inline data-swup-ignore-script>
29
  (function() {
30
    // 换成你刚才搭建好的私人 API 网址
31
    const apiUrl = "https://你的API域名.com/";
32

33
    const bgBox = document.getElementById('my-custom-bg');
34
    if (!bgBox) return;
35

36
    const img = new Image();
37

38
    // 加上时间戳强制浏览器刷新，防止使用缓存图
39
    img.src = apiUrl + '?t=' + new Date().getTime();
40

41
    // 优雅加载：等图片在后台完全下载好再显示，防止画面撕裂
42
    img.onload = () => {
43
      bgBox.style.backgroundImage = `url('${img.src}')`;
44
      bgBox.classList.add('loaded'); // 加上类名，触发 CSS 淡入动画
45
    };
46
  })();
47
</script>

(注意：在 Astro 或使用了类似 Swup 路由过渡效果的框架中，script 标签上添加 is:inline data-swup-ignore-script 可以防止页面切换时背景重新闪烁加载。)

✨ 细节拉满：CSS 毛玻璃特效#

细心的你可能注意到了 <style> 代码块中的这两个属性：

1
filter: blur(3px);
2
transform: scale(1.02);

这就是让背景瞬间变高级的秘密武器！

filter: blur(3px)：给背景加上了高斯模糊滤镜，使其变成“磨砂玻璃”质感。这样不仅能烘托博客氛围，还不会喧宾夺主，确保了前面文章文字的清晰可读。
transform: scale(1.02)：这是一个隐藏技巧！当浏览器对满屏图片进行模糊处理时，图片边缘会向内收缩，导致屏幕四周漏出难看的底色边框。将图片放大 2%，完美地把模糊产生的瑕疵藏到了屏幕之外。

🎉 总结#

通过极简的 PHP API 加上原生 JavaScript 的优雅预加载，我们不仅绕过了静态博客的限制，还完美规避了跨域问题。看着每次刷新都能丝滑淡入的高级模糊背景，折腾的成就感直接拉满！

💡 为什么不直接改配置文件？#

🚀 第一步：搭建私人专属的随机图 API (后端)#

🎨 第二步：在博客中植入“魔法阵” (前端)#

✨ 细节拉满：CSS 毛玻璃特效#

🎉 总结#

评论区