引言#

如果你用过WordPress，Halo等动态博客框架，你大概会在用户视角访问博文的时候看到浏览量这个信息。

这个原理很简单，因为动态博客依赖于一个VPS，只需要让用户每次访问的时候给浏览量+1即可。

那么如果我们是静态博客呢？

我们可以依赖一些第三方服务，比如Umami Cloud。在你的静态博客的head注入一个js，这样你就可以看到你的站点分析了，类似下图

现在我们可以看到网站整体的访问量和每个文章（即/posts/xxx）的访问量了，但是我们要如何展示给用户呢？

1. 分析实现过程#

因为我采用的是免费方案，Umami Cloud这个是免费，因此不能新建一个用户，同时博客部署都是采用免费方案。

为了稍微安全一点，不建议采用Umami Cloud账号登录

当然如果只是用于测试，那么无所谓啦~

注意这里的 IrVVYJ4qc2J3tc7s ，每个站点都不一样

~~接着我们请求 https://us.umami.is/api/share/IrVVYJ4qc2J3tc7s，得到token和 websiteId~~

这个是2025年10月12日修改的，直接采用官网的，之前的方案不能用了

接着我们请求https://cloud.umami.is/analytics/us/api/share/IrVVYJ4qc2J3tc7s，得到token和websiteId

1
{
2
    "websiteId": "77083547-4c2e-4183-b842-520d9de3d82b",
3
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ3ZWJzaXRlSWQiOiI3NzA4MzU0Ny00YzJlLTQxODMtYjg0Mi01MjBkOWRlM2Q4MmIiLCJpYXQiOjE3NTgwMzgyMzh9.7RNrqCaOvgKYFifvpbmtsZR1ykAETgqqOrPgFUpWtng"
4
}

这个时候可以通过/api/websites/:websiteId/stats 获取网站统计汇总。

携带请求头 x-umami-share-token 值为上一步获得的Token

2.0：每次访问都需要携带token才能正常使用，虽然访问https://us.umami.is/api/share/IrVVYJ4qc2J3tc7s中 x-umami-share-token是undefined，但是需要数据的请求都是有值的，

3.0：现在请求链接：https://cloud.umami.is/analytics/us/share/i6f3UwPY4n0w1LJa

1
https://us.umami.is/api/websites/77083547-4c2e-4183-b842-520d9de3d82b/stats?startAt=0&endAt=1757937599999&unit=hour&timezone=Asia/Hong_Kong&url=/posts/cf-fastip/&compare=false
2

3

4
https://cloud.umami.is/analytics/us/api/websites/77083547-4c2e-4183-b842-520d9de3d82b/stats?startAt=0&endAt=1757937599999&unit=hour&timezone=${encodeURIComponent(umamiConfig.timezone)}&path=eq.%2Fposts%2F${slug}%2F&compare=false`;

这里解释几个关键Params，其他的照搬

startAt：统计开始时间。Unix时间戳，我们填写为0让Umami从1970年开始统计
endAt：统计结束时间。Unix时间戳，我们可以使用 Date.now() ，即当前时间，和startAt参数联动即可实现统计总浏览量
url（弃用）：要查询的路径，填写为你的文章页去除了Host的路径，如 /posts/hello 。注意！Umami会将 /posts/hello 和 /posts/hello/ 视为两个不同的路径，请注意你的博客框架是否使用 /
path=eq.：通过 path 参数配合 eq. 前缀（表示 “等于”）筛选路径，这是 Umami 支持的 “高级筛选语法”（类似 SQL 的条件表达式），功能上与 url 参数等效，但格式更规范（支持更多条件如 contains 包含、ne 不等于等）。

你会得到

1
// Umami2.0版本
2
{
3
    "pageviews": {
4
        "value": 26,
5
        "prev": 0
6
    },
7
    "visitors": {
8
        "value": 5,
9
        "prev": 0
10
    },
11
    "visits": {
12
        "value": 9,
13
        "prev": 0
14
    },
15
    "bounces": {
16
        "value": 3,
17
        "prev": 0
18
    },
19
    "totaltime": {
20
        "value": 2885,
21
        "prev": 0
22
    }
23
}
24

25
// Umami3.0版本
26

27
{
28
    "pageviews": 125,
29
    "visitors": 2,
30
    "visits": 4,
31
    "bounces": 1,
32
    "totaltime": 5713,
33
    "comparison": {
34
        "pageviews": 0,
35
        "visitors": 0,
36
        "visits": 0,
37
        "bounces": 0,
38
        "totaltime": 0
39
    }
40
}

2.0版本：~~pageviews.vlaue 即浏览量。 visits.value 即访问次数。~~

3.0版本：pageviews 即浏览量。 visits 即访问次数。

Tips：浏览量记录为任意用户只要访问了则计数一次。而访问数记录不会记录单IP多次重复访问和同一时间段的多次请求不同页面

2. 代码展示#

src\config.ts中增加UmamiConfig 和 statsConfig

1
export const umamiConfig: UmamiConfig = {
2
  enable: true,
3
  baseUrl: "https://us.umami.is",
4
    baseUrl: "https://cloud.umami.is",
5
  shareId: "IrVVYJ4qc2J3tc7s",
6
  timezone: "Asia/Shanghai",
7
};
8

9
export const statsConfig = {
10
  viewsText: "浏览量",
11
  visitsText: "访客",
12
  loadingText: "统计加载中...",
13
  unavailableText: "统计不可用。",
14
  getStatsText: (pageViews: number, visits: number) =>
15
    `${statsConfig.viewsText} ${pageViews} · ${statsConfig.visitsText} ${visits}`,
16
};

src\types\config.ts配置UmamiConfig类别

1
export type UmamiConfig = {
2
  enable: boolean;
3
  baseUrl: string;
4
  shareId: string;
5
  timezone: string;
6
};

新增public\js\umami-share.js

1
((global) => {
2
  const cacheKey = "umami-share-cache";
3
  const cacheTTL = 3600_000; // 1h
4

5
  async function fetchShareData(baseUrl, shareId) {
6
    const cached = localStorage.getItem(cacheKey);
7
    if (cached) {
8
      try {
9
        const parsed = JSON.parse(cached);
10
        if (Date.now() - parsed.timestamp < cacheTTL) {
11
          return parsed.value;
12
        }
13
      } catch {
14
        localStorage.removeItem(cacheKey);
15
      }
16
    }
17
    const res = await fetch(`${baseUrl}/api/share/${shareId}`);
18
        const res = await fetch(`${baseUrl}/analytics/us/api/share/${shareId}`);
19
    if (!res.ok) {
20
      throw new Error("获取 Umami 分享信息失败");
21
    }
22
    const data = await res.json();
23
    localStorage.setItem(
24
      cacheKey,
25
      JSON.stringify({ timestamp: Date.now(), value: data }),
26
    );
27
    return data;
28
  }
29

30
  /**
31
   * 获取 Umami 分享数据（websiteId、token）
32
   * 在缓存 TTL 内复用；并用全局 Promise 避免并发请求
33
   * @param {string} baseUrl
34
   * @param {string} shareId
35
   * @returns {Promise<{websiteId: string, token: string}>}
36
   */
37
  global.getUmamiShareData = (baseUrl, shareId) => {
38
    if (!global.__umamiSharePromise) {
39
      global.__umamiSharePromise = fetchShareData(baseUrl, shareId).catch(
40
        (err) => {
41
          delete global.__umamiSharePromise;
42
          throw err;
43
        },
44
      );
45
    }
46
    return global.__umamiSharePromise;
47
  };
48

49
  global.clearUmamiShareCache = () => {
50
    localStorage.removeItem(cacheKey);
51
    delete global.__umamiSharePromise;
52
  };
53
})(window);

文章页面src\components\PostMeta.astro增加显示浏览量

1
import { Icon } from "astro-icon/components";
2
// 导入statsConfig, umamiConfig配置
3
import { statsConfig, umamiConfig } from "../config";
4
import I18nKey from "../i18n/i18nKey";
5
import { i18n } from "../i18n/translation";
6
import { formatDateToYYYYMMDD } from "../utils/date-utils";
7
import { getCategoryUrl, getTagUrl } from "../utils/url-utils";
8

9
interface Props {
10
  class: string;
11
  published: Date;
12
  updated?: Date;
13
  tags: string[];
14
  category: string | null;
15
  hideTagsForMobile?: boolean;
16
  hideUpdateDate?: boolean;
17
    //当前页面
18
  slug?: string;
19
}
20
const {
21
  published,
22
  updated,
23
  tags,
24
  category,
25
  hideTagsForMobile = false,
26
  hideUpdateDate = false,
27
    //当前页面
28
  slug,
29
} = Astro.props;
30
const className = Astro.props.class;
31

32

33
--------------------------------------------------------------------------------------------
34

35
<!-- page views / 页面显示 -->
36
    {slug && (
37
        <div class="flex items-center">
38
            <div class="meta-icon">
39
                <Icon name="material-symbols:visibility-outline-rounded" class="text-xl"></Icon>
40
            </div>
41
            <span class="text-50 text-sm font-medium" id="page-views-display">{statsConfig.loadingText}</span>
42
        </div>
43
    )}
44
</div>
45

46
--------------------------------------------------------------------------------------------
47
{slug && (
48
    <script define:vars={{ slug, umamiConfig, unavailableText: statsConfig.unavailableText, viewsText: statsConfig.viewsText, visitsText: statsConfig.visitsText }}>
49
        // 客户端统计文案生成函数
50
        function generateStatsText(pageViews, visits) {
51
            return `${viewsText} ${pageViews} · ${visitsText} ${visits}`;
52
        }
53

54
        // 获取访问量统计
55
        async function fetchPageViews(isRetry = false) {
56
            if (!umamiConfig.enable) {
57
                return;
58
            }
59

60
            try {
61
                // 调用全局工具获取 Umami 分享数据
62
                const { websiteId, token } = await getUmamiShareData(umamiConfig.baseUrl, umamiConfig.shareId);
63

64
                // 第二步：获取统计数据
65
                const currentTimestamp = Date.now();
66
                const statsUrl = `${umamiConfig.baseUrl}/api/websites/${websiteId}/stats?startAt=0&endAt=${currentTimestamp}&unit=hour&timezone=${encodeURIComponent(umamiConfig.timezone)}&url=%2Fposts%2F${slug}%2F&compare=false`;
67

68
                const statsUrl = `${umamiConfig.baseUrl}/analytics/us/api/websites/${websiteId}/stats?startAt=0&endAt=${currentTimestamp}&unit=hour&timezone=${encodeURIComponent(umamiConfig.timezone)}&path=eq.%2Fposts%2F${slug}%2F&compare=false`;
69

70

71
                const statsResponse = await fetch(statsUrl, {
72
                    headers: {
73
                        'x-umami-share-token': token
74
                    }
75
                });
76

77
                if (!statsResponse.ok) {
78
                    if (statsResponse.status === 401 && !isRetry) {
79
                        clearUmamiShareCache();
80
                        return fetchPageViews(true);
81
                    }
82
                    throw new Error('获取统计数据失败');
83
                }
84

85
                const statsData = await statsResponse.json();
86
                const pageViews = statsData.pageviews?.value || 0;
87
                const visits = statsData.visits?.value || 0;
88
                const pageViews = statsData.pageviews || 0;
89
                const visits = statsData.visits || 0;
90

91
                const displayElement = document.getElementById('page-views-display');
92
                if (displayElement) {
93
                    displayElement.textContent = generateStatsText(pageViews, visits);
94
                }
95
            } catch (error) {
96
                console.error('Error fetching page views:', error);
97
                const displayElement = document.getElementById('page-views-display');
98
                if (displayElement) {
99
                    displayElement.textContent = unavailableText;
100
                }
101
            }
102
        }
103

104
        // 页面加载完成后获取统计数据
105
        if (document.readyState === 'loading') {
106
            document.addEventListener('DOMContentLoaded', fetchPageViews);
107
        } else {
108
            fetchPageViews();
109
        }
110
    </script>
111
)}

首页卡片文章src\components\PostCard.astro 增加显示浏览量

1
import { statsConfig, umamiConfig } from "../config";
2

3
--------------------------------------------------------------------------------------------
4

5
<!-- word count and read time and 浏览量 -->
6
        <div class="text-sm text-black/30 dark:text-white/30 flex gap-4 transition">
7
            <div>
8
                {remarkPluginFrontmatter.words} {" " + i18n(remarkPluginFrontmatter.words === 1 ? I18nKey.wordCount : I18nKey.wordsCount)}
9
            </div>
10
            <div>|</div>
11
            <div>
12
                {remarkPluginFrontmatter.minutes} {" " + i18n(remarkPluginFrontmatter.minutes === 1 ? I18nKey.minuteCount : I18nKey.minutesCount)}
13
            </div>
14
            <div>|</div>
15
            <div>
16
                <span class="text-50 text-sm font-medium" id={`page-views-${entry.slug}`}>{statsConfig.loadingText}</span>
17
            </div>
18
        </div>
19

20
--------------------------------------------------------------------------------------------
21
<script define:vars={{ entry, umamiConfig, unavailableText: statsConfig.unavailableText, viewsText: statsConfig.viewsText, visitsText: statsConfig.visitsText }}>
22
    // 客户端统计文案生成函数
23
    function generateStatsText(pageViews, visits) {
24
        return `${viewsText} ${pageViews} · ${visitsText} ${visits}`;
25
    }
26

27
    // 获取文章浏览量统计
28
    async function fetchPostCardViews(slug) {
29
        if (!umamiConfig.enable) {
30
            return;
31
        }
32

33
        try {
34
            // 调用全局工具获取 Umami 分享数据
35
            const { websiteId, token } = await getUmamiShareData(umamiConfig.baseUrl, umamiConfig.shareId);
36

37
            // 第二步：获取统计数据
38
            const currentTimestamp = Date.now();
39
            const statsUrl = `${umamiConfig.baseUrl}/api/websites/${websiteId}/stats?startAt=0&endAt=${currentTimestamp}&unit=hour&timezone=${encodeURIComponent(umamiConfig.timezone)}&url=%2Fposts%2F${slug}%2F&compare=false`;
40

41
            const statsUrl = `${umamiConfig.baseUrl}/analytics/us/api/websites/${websiteId}/stats?startAt=0&endAt=${currentTimestamp}&unit=hour&timezone=${encodeURIComponent(umamiConfig.timezone)}&path=eq.%2Fposts%2F${slug}%2F&compare=false`;
42

43
            const statsResponse = await fetch(statsUrl, {
44
                headers: {
45
                    'x-umami-share-token': token
46
                }
47
            });
48

49
            if (statsResponse.status === 401) {
50
                clearUmamiShareCache();
51
                return await fetchPostCardViews(slug);
52
            }
53

54
            if (!statsResponse.ok) {
55
                throw new Error('获取统计数据失败');
56
            }
57

58
            const statsData = await statsResponse.json();
59
            const pageViews = statsData.pageviews?.value || 0;
60
            const visits = statsData.visits?.value || 0;
61

62
            const pageViews = statsData.pageviews || 0;
63
            const visits = statsData.visits || 0;
64
            const displayElement = document.getElementById(`page-views-${slug}`);
65
             if (displayElement) {
66
                 displayElement.textContent = generateStatsText(pageViews, visits);
67
             }
68
        } catch (error) {
69
            console.error('Error fetching page views for', slug, ':', error);
70
            const displayElement = document.getElementById(`page-views-${slug}`);
71
            if (displayElement) {
72
                displayElement.textContent = unavailableText;
73
            }
74
        }
75
    }
76

77
    // 页面加载完成后获取统计数据
78
    function initPostCardStats() {
79
        const slug = entry.slug;
80
        if (slug) {
81
            fetchPostCardViews(slug);
82
        }
83
    }
84

85
    if (document.readyState === 'loading') {
86
        document.addEventListener('DOMContentLoaded', initPostCardStats);
87
    } else {
88
        initPostCardStats();
89
    }
90
</script>
91
<style define:vars={{coverWidth}}>
92
</style>

显示总的浏览量src\components\widget\Profile.astro

1
import { profileConfig, statsConfig, umamiConfig } from "../../config";
2

3
--------------------------------------------------------------------------------------------
4

5
 <!-- 全站访问量统计 -->
6
         <div class="text-center text-sm text-neutral-500 dark:text-neutral-400 mt-3 pt-3 border-t border-neutral-200 dark:border-neutral-700">
7
            <div class="flex items-center justify-center gap-1">
8
                <Icon name="material-symbols:visibility-outline" class="text-base"></Icon>
9
                <span id="site-stats">{statsConfig.loadingText}</span>
10
            </div>
11
        </div>
12

13
--------------------------------------------------------------------------------------------
14

15
<script define:vars={{ umamiConfig, unavailableText: statsConfig.unavailableText, viewsText: statsConfig.viewsText, visitsText: statsConfig.visitsText }}>
16
    // 获取全站访问量统计
17
    // 客户端统计文案生成函数
18
    function generateStatsText(pageViews, visits) {
19
        return `${viewsText} ${pageViews} · ${visitsText} ${visits}`;
20
    }
21

22
    async function loadSiteStats() {
23
        if (!umamiConfig.enable) {
24
            return;
25
        }
26

27
        try {
28
            // 调用全局工具获取 Umami 分享数据
29
            const { websiteId, token } = await getUmamiShareData(umamiConfig.baseUrl, umamiConfig.shareId);
30

31
            // 第二步：获取全站统计数据（不指定url参数获取全站数据）
32
            const currentTimestamp = Date.now();
33
            const statsUrl = `${umamiConfig.baseUrl}/api/websites/${websiteId}/stats?startAt=0&endAt=${currentTimestamp}&unit=hour&timezone=${encodeURIComponent(umamiConfig.timezone)}&compare=false`;
34

35
            const statsUrl = `${umamiConfig.baseUrl}/analytics/us/api/websites/${websiteId}/stats?startAt=0&endAt=${currentTimestamp}&unit=hour&timezone=${encodeURIComponent(umamiConfig.timezone)}&compare=false`;
36

37

38
            const statsResponse = await fetch(statsUrl, {
39
                 headers: {
40
                     'x-umami-share-token': token
41
                 }
42
             });
43

44
            if (statsResponse.status === 401) {
45
                // token 失效，清理缓存后重新获取一次
46
                clearUmamiShareCache();
47
                return await loadSiteStats();
48
            }
49

50
            if (!statsResponse.ok) {
51
                throw new Error('获取统计数据失败');
52
            }
53

54
            const statsData = await statsResponse.json();
55
            const pageviews = statsData.pageviews?.value || 0;
56
            const visitors = statsData.visits?.value || 0;
57

58
            const pageviews = statsData.pageviews || 0;
59
            const visitors = statsData.visits || 0;
60

61
            const statsElement = document.getElementById('site-stats');
62
            if (statsElement) {
63
                statsElement.textContent = generateStatsText(pageviews, visitors);
64
            }
65
        } catch (error) {
66
            console.error('获取全站统计失败:', error);
67
            const statsElement = document.getElementById('site-stats');
68
            if (statsElement) {
69
                statsElement.textContent = unavailableText;
70
            }
71
        }
72
    }
73

74
    // 页面加载完成后获取统计数据
75
    document.addEventListener('DOMContentLoaded', loadSiteStats);
76
</script>

3. 代码引用#

1
<!DOCTYPE html>
2
<html lang={siteLang} class="bg-[var(--page-bg)] transition text-[14px] md:text-[16px]"
3
    data-overlayscrollbars-initialize
4
>
5
  <head>
6

7
    <title>{pageTitle}</title>
8
    // ....
9
    <script defer src="https://cloud.umami.is/script.js" data-website-id="f11536ad-eac1-434b-a0c7-fc78faa63405"></script>
10
    <script src="/js/umami-share.js" defer></script>
11
    {favicons.map(favicon => (
12
      <link rel="icon"
13
          href={favicon.src.startsWith('/') ? url(favicon.src) : favicon.src}
14
          sizes={favicon.sizes}
15
          media={favicon.theme && `(prefers-color-scheme: ${favicon.theme})`}
16
      />
17
    ))}

公告

引言#

1. 分析实现过程#

2. 代码展示#

3. 代码引用#