﻿---
title: "使用指南 8：把博客发布到自己的域名"
description: "说明 Anglefeint 的静态部署、域名与环境覆盖、构建和图片文件、搜索及公开导出，以及可选 GA4 接入。"
url: "https://demo.anglefeint.com/zh/blog/starter-guide-deployment/"
language: "zh"
author: "Anglefeint"
published: "2026-11-13T00:00:00.000Z"
updated: "2026-11-13T00:00:00.000Z"
---

# 使用指南 8：把博客发布到自己的域名

**版本说明：** 正常 build／CI doctor 自动补齐图片需要主题 0.36.2 或更新版本；0.36.1 需先运行 dev 或 prepare-covers。显式 `prepare-covers --check` 保持只读。

本篇是入门教程的第 8 / 8 篇。[查看完整教程顺序](https://demo.anglefeint.com/zh/blog/starter-guide-1-configure-your-site/#tutorial-order) · [按字段查配置字典](https://demo.anglefeint.com/zh/blog/config-reference/)。

本地已经能打开博客后，发布需要做三件事：确认最终域名、生成完整静态文件、让托管服务用这个域名提供这些文件。主题不会替你购买域名、修改 DNS 或自动登录托管平台。

当前 starter 默认构建静态网站，不需要生产环境一直运行 Node.js，也不需要为了发布静态页面添加 SSR adapter。下面以 npm 项目和默认输出目录 `dist/` 为例。

## 1\. 先确定正式网站地址

准备一个由自己管理的域名，例如 `https://blog.example.com`。在 `src/site.config.ts` 现有顶层 `site` 中合并：

```ts
site: {
  url: 'https://blog.example.com',
},
```

填写最终对外访问的地址，不填 localhost、某篇文章的网址或托管控制台地址。其他站点信息保留不变。

这个值会用于生成 canonical、RSS、sitemap、分享图和公开内容链接。它不改变本地开发服务地址，也不会把一个尚未绑定的域名自动指向网站。

### 检查有没有旧的环境覆盖

如果项目 `.env`、适用的 `.env.*` 文件或托管构建环境中设置了 `PUBLIC_SITE_URL`，它优先于配置文件。只改 site.url 但结果仍是旧域名时，应同时检查这些位置。普通 dev 使用 development 模式，普通 build 使用 production 模式；自定义 `--mode` 时还会读取对应模式配置，不能只检查 `.env`。

不需要环境覆盖就移除对应变量，统一使用 site.url；需要区分环境时，在各自构建环境设置正确值。修改后重新构建，不能只在旧产物里手动改一个链接。

### 使用域名根目录

当前主题按域名根目录部署使用，例如 `https://blog.example.com/`。部署到 `https://example.com/my-blog/` 这种子路径仍需额外适配，不能只设置 Astro base 就认为全部页面和资源都兼容。

选择托管方式时确认它能提供根目录站点、静态目录的 index.html 和正常的子页面路径。如果使用 GitHub Pages，优先按它的站点域名／自定义域名流程部署，不能直接把项目子路径教程当作本主题已经支持的配置。平台具体设置参见 [Astro 部署文档](https://docs.astro.build/en/guides/deploy/)及其中对应的托管指南。

## 2\. 把需要的源文件准备完整

部署应使用你自己的博客项目及实际内容所在分支，不是把主题维护仓库的演示内容直接当成个人博客。源码至少包含项目配置、内容、依赖清单和需要的资源。

新增或替换本地封面、碎片图片后，先在本地 dev 或 doctor 中准备响应式文件，再提交：

*   文章、碎片、自建页面和 `src/site.config.ts`。
*   文章引用的原图、public 图片、图标和实际需要的音乐等资源。
*   整个 `src/assets/blog/covers/`，包括 manifest.json、generated/ 和使用到的 originals/。
*   `package.json`、`package-lock.json`，以及项目原有 Astro 配置和托管设置。

原图不一定放在 originals：放在文章旁边或 public 中的原文件也要提交。图片准备细节见[给文章和碎片添加图片](https://demo.anglefeint.com/zh/blog/starter-guide-images/)。

**部署端的普通 build 会自动补齐缺失、过期或损坏的响应式图片，CI doctor 同样会准备。** 有效派生文件直接复用；原图缺失、无法解码或路径越界仍会报错。提交派生文件可加快后续构建，但不再是正常 build 成功的前提，也不需要部署平台保留图片缓存。

基于 Git 构建的部署不需要提交 node\_modules、`.astro` 或 dist；平台会安装依赖并生成产物。不要把本机的依赖目录作为静态网站上传。环境文件若没有进入仓库，在平台上配置需要的环境变量；PUBLIC\_ 变量用于公开站点信息，不适合存放私密凭据。

## 3\. 本地检查并预览真正的构建结果

先按 Ctrl+C 停止 dev，确保当前终端位于项目根目录，然后运行：

```bash
npm run doctor
npm run preview
```

打开 preview 打印的网址，检查首页、文章、图片、语言菜单和文章搜索。新增语言或开启可选页面时，也检查它们的入口。评论等外部服务需要浏览器实际连接才能确认，本地构建通过不会证明远程权限配置正确。

这些命令的职责不同：

| 命令 | 做什么 |
| --- | --- |
| `npm run dev` | 本地开发，相关图片可自动准备；没有构建后的全文搜索索引 |
| `npm run doctor` | 本地准备图片，执行 Astro 检查和构建；About 开启时还检查其运行时配置 |
| `npm run check` | 当前 starter 中同样调用 doctor，不必与 doctor 连续重复执行 |
| `npm run build` | 准备需要的持久图片并构建网站，不执行 doctor 的其他检查 |
| `npm run preview` | 提供已经构建的 dist，不重新构建、不发布网站 |

任何检查或构建失败时先修复错误，不要部署残留 dist。doctor 成功后已有构建结果，无需紧接着再执行 check 和 build。preview 按 Ctrl+C 停止。

## 4\. 部署完整静态产物

你可以连接 Git 仓库让平台构建，也可以本地构建后手动上传。两种方式最终都提供同一份静态输出。

### 方式一：托管平台从 Git 构建

在所选平台连接自己的仓库，并配置：

| 项目 | 当前 starter 的设置 |
| --- | --- |
| 构建分支 | 你实际维护博客内容的分支 |
| 项目根目录 | 包含该博客 package.json 的目录，不一定是整个仓库最外层 |
| Node.js | 满足项目和依赖要求，当前 starter 声明 22.12.0 或更新版本 |
| 安装 | npm 项目可使用 `npm ci`，需要已提交且与 package.json 一致的 package-lock.json |
| 构建命令 | `npm run build` |
| 输出目录 | `dist`，相对于项目根目录 |

如果平台自动执行依赖安装，不必重复添加一次安装命令；如果要求自己写完整构建脚本，应先安装再 build。不要在构建脚本里重复运行 doctor、check、build，无需另加图片补生成步骤；正常 build 已统一处理派生资源，但原图必须提交。

平台的框架预设、分支和安装步骤以它的实际设置为准。选择静态输出方式，不需要把 npm run dev 或 npm run preview 作为生产启动命令。

### 方式二：上传本地构建结果

本地 doctor 成功后，将 `dist/` 的全部内容上传到托管服务的网站根目录。如果服务让你选择输出文件夹，就选择 dist；如果让你上传网站文件，就上传 dist 里面的内容，不要额外多套一层 dist 路径。

除 HTML 外，还要包含 `_astro/`、`_blog-covers/`、`_social/`、搜索索引以及本次构建实际生成的其他文件。以下划线开头的目录不是可以忽略的临时文件；只传 HTML 会导致样式、脚本、图片或搜索缺失。

重新发布时使用平台的完整部署／替换机制，避免只覆盖新文件却留下已删除文章、旧分页或旧语言文件。删除本地 Markdown 不会让手动上传服务器上的旧 HTML 自动消失。

## 5\. 在平台绑定域名，再配置 DNS

在托管平台中添加要使用的自定义域名，然后按它提供的记录值，在域名 DNS 管理处添加或修改记录。根域名与子域名的记录类型及目标可能不同，应使用平台给出的实际值，不要照抄示例 IP。

等待平台确认域名及 HTTPS 证书可用，再通过正式地址打开网站。若同时使用裸域名和 www 等多个地址，选择一个作为主地址，并在托管侧将其他地址重定向到它，site.url 也填写主地址。

canonical 只是页面元信息，不是访问重定向。主题中的 site.url 不会替你执行 DNS、证书签发或多域名跳转；这些由域名和托管设置负责。更换主域名后重新构建并部署，更新仍保留旧域名的环境覆盖值。

## 6\. 发布后核对页面和公开输出

通过正式域名检查一篇文章的直接链接，刷新后也应能打开；不能只从首页点进去成功就认为所有路径都正确。再检查图片、代码样式、语言切换和搜索。仅在 dev 中测试过的功能，需要在已构建网站上重新确认。

主题默认接入这些静态输出，不需要再安装一套相同集成：

| 地址示例 | 用途 |
| --- | --- |
| `/robots.txt` | 提供抓取规则及 sitemap 地址，不是访问权限控制 |
| `/sitemap-index.xml` | 站点地图入口，链接应使用正式域名 |
| `/zh/rss.xml` | 中文文章订阅，其他启用语言替换 zh |
| `/llms.txt` | AI 可读内容总索引 |
| `/zh/llms.txt`、`/zh/llms-full.txt` | 该语言有导出内容时的索引与全文合集 |
| `/zh/blog/my-first-post/index.md` | 对应公开文章的 Markdown 输出，示例 slug 换成真实文章 |
| `/zh/fragments/index.md`、`/zh/about/index.md` | 对应页面启用且符合导出条件时的公开内容 |

文章 sitemap 更新日期使用 updatedDate，未填时使用 pubDate，不会每次构建伪造新日期。关闭的语言／页面不应期待有对应公开导出；文章搜索的 search: false 不等于文章私密，也不会自动禁止其他公开输出。

AI 导出包含公开文章、启用的 Fragments 和 About 内容；评论和装饰工具界面不在导出正文中。实际 noindex 页面或站外 canonical 页面不纳入导出，用户自有文件与生成路径冲突时会停止构建，不会直接覆盖。导出文件和发现链接随重新构建更新，需要一起部署。

这些元信息与文本输出有助于发现和读取，不保证搜索引擎收录、AI 引用或流量增长。

### 托管响应头的区别

构建会在 dist/\_headers 中为 `/:locale/terminal/*` 补充 `X-Robots-Tag: noindex`，保留已有规则，不修改源 public/\_headers。支持这种文件格式的托管服务会应用它；其他服务需要等效响应头设置。

Astro preview 不会模拟托管平台的 \_headers 规则。要判断响应头是否生效，应检查正式服务的响应，不能只看本地文件存在；无需为了这条规则添加 Node 服务器。

域名与环境变量的具体优先级见[站点字典](https://demo.anglefeint.com/zh/blog/config-site-chrome/#environment)，公开说明的逐字段定义见[GA4 与 AI 阅读补充字典](https://demo.anglefeint.com/zh/blog/config-analytics-ai/#supplement)。

## 7\. 按需补充 AI 阅读说明

普通发布无需增加这项配置。如果想说明站点背景或提供额外资料，可以在配置顶层合并：

```ts
aiReadableContent: {
  notes: '本站记录个人学习过程，内容可能持续修订。',
  links: [{ label: '项目主页', href: 'https://example.com/project' }],
},
```

notes 支持 Markdown，links 每项填写 label 和 href。链接应为可公开访问的 HTTP(S) 地址；根路径等相对地址会按站点地址解析。这是公开的站点补充说明，不替换文章正文，也不是给文章增加隐私限制。

按语言覆盖时，使用 `i18n.locales.<代码>.aiReadableContent`。例如让中文使用自己的说明且不列附加链接：

```ts
i18n: {
  locales: {
    zh: {
      aiReadableContent: {
        notes: '中文内容是作者自己的学习笔记。',
        links: [],
      },
    },
  },
},
```

省略某个字段继承全局值；notes: ‘’ 或 links: \[\] 明确隐藏对应部分。补充说明会进入相关索引、全文合集和单篇 Markdown，填写前确认愿意公开，修改后重新构建。

## 8\. 按需启用 GA4 访问统计

默认不加载 Google 统计脚本。需要统计时，先在 Google Analytics 的网页数据流中取得以 G- 开头的 Measurement ID；查找位置可参考 [Google 官方说明](https://support.google.com/analytics/answer/9539598)。主题只接受 G- 形式的 ID，不使用数字属性 ID、GTM 容器 ID或其他标识代替。

在配置顶层、与 site 同一级，合并：

```ts
analytics: {
  googleAnalyticsId: 'G-XXXXXXXXXX',
},
```

替换成真实 ID；空字符串关闭。格式错误会报配置错误。一个 ID 可以统计各语言页面，按路径区分语言即可；不必每种主题或语言粘一份脚本。

主题只在生产构建且已配置 ID 时输出加载器，dev 不发送。浏览器访问 localhost、其子域或回环等本地地址时，加载器跳过上报；使用局域网 IP 或远程预览域名访问生产构建则可能上报，不要把所有 preview 都当作被排除。

重新部署后，用正式地址访问并查看 GA4 实时报告。脚本拦截、网络和统计端设置都可能影响结果。不要同时用手工代码、GTM 或其他注入工具重复安装同一统计；本功能没有附带同意管理界面，需要时应自行接入相应方案。

## 9\. 部署失败或线上不对时

| 现象 | 优先检查 |
| --- | --- |
| npm ci 失败 | Node／依赖要求，以及 package-lock 是否提交并与 package.json 一致 |
| 提示图片 missing／stale／modified | 确认原图已提交且路径合法；正常 build 会补齐派生文件，–check 只读检查需先准备 |
| 构建成功但页面 404 | 输出目录、发布分支、网站根目录和目录 index 支持；是否误用未适配的子路径 |
| 首页能开，文章刷新 404 | 平台是否提供真实静态子路径，是否错误地只发布首页或套用 SPA 回退 |
| 页面没样式、图片或搜索 | 是否完整部署 dist，资源子目录是否遗漏，路径是否被改写 |
| canonical／RSS 仍是示例域名 | site.url、PUBLIC\_SITE\_URL 及构建模式的环境值，是否重新构建部署 |
| 改配置后线上没变化 | 是否部署了正确项目、分支和最新提交，而不是只修改本机文件 |
| 删除文章后旧链接还能访问 | 是否仍残留旧部署文件或缓存；检查完整替换与托管缓存 |
| GA4 没有数据 | 是否配置真实 G- ID、使用生产构建和非本地地址，脚本是否被拦截 |

日常更新继续遵循“本地编辑与准备 → 检查预览 → 提交源文件 → 构建部署”。升级主题见[安装教程](https://demo.anglefeint.com/zh/blog/starter-guide-1-configure-your-site/)，语言路径见[让更多语言的读者使用博客](https://demo.anglefeint.com/zh/blog/starter-guide-languages/)。

## 教程导航与配置查阅

首次发布到这里完成。以后可按要修改的内容回看对应教程或查询配置字典。

[上一篇：让更多语言的读者使用博客](https://demo.anglefeint.com/zh/blog/starter-guide-languages/) · [八篇教程总入口](https://demo.anglefeint.com/zh/blog/starter-guide-1-configure-your-site/#tutorial-order)。

本篇相关字段：[域名与环境覆盖](https://demo.anglefeint.com/zh/blog/config-site-chrome/)、[GA4 与 AI 阅读补充](https://demo.anglefeint.com/zh/blog/config-analytics-ai/)、[搜索资源](https://demo.anglefeint.com/zh/blog/config-search/)。完整路径、默认值和限制见[配置字典总入口](https://demo.anglefeint.com/zh/blog/config-reference/)。
