手册：搭建博客网站

从0-1, 基于hexo+ stellar+ vercel搭建博客所涉及到的方方面。

每年11/26日前记得重新申请域名的ssl证书；若配置了七牛云图床，也要相应更新证书

博客构思

我们想要做出一个什么样的个人博客？应该是能满足记录生活、学习笔记、bug收录、项目展示、产品推广、个人简历、朋友互动等等，最主要是简单易上手且方便部署。为此选择了Hexo。

环境准备

有终端

Windows系统可以用powershell或CMD，也可以用git-bash

可正常访问GitHub

有问题请参考。

有Node.js

博客框架是基于Node.js的，所以要安装。另外担心可能存在多个Node.js版本造成的混乱，这里我直接安装了NVM(Node Version Manager)，一个用于管理 Node.js版本的工具。如需安装，请参考教程，总结如下

下载nvm
选择最新版的nvm-setup.zip下载，解压。
安装nvm
执行nvm-setup.exe。在安装前的设置中，会提示指定两个安装路径：nvm的、Nodejs的，建议非C盘、无中文(请记住你的安装路径)。最终你将得到一个仅十几兆的nvm文件夹，别担心，它就是很小。
配置nvm

环境变量
系统搜索编辑系统环境变量→ 在用户变量、系统变量里都要保证有如下键值对：
NVM_HOME: 你的nvm路径, 如"D:\my_apps\for_produce\nvm\" NVM_SYMLINK: 你的node路径, 如"D:\my_apps\for_produce\Nodejs\"
然后在系统变量的path中添加两个值：%NVM_HOME%和%NVM_SYMLINK%。
镜像源
有教程说国内要用淘宝源, 即在终端执行如下即可：
nvm node_mirror https://npm.taobao.org/mirrors/node/ nvm npm_mirror https://npm.taobao.org/mirrors/npm/
但我发现我使用时，这些url都报错。我还是不设置镜像源吧，就默认官方的好了。
最后检验是否安装成功：nvm -v

安装指定版本的Nodejs
安装 nvm install 20.10.0

这会在nvm的安装目录下生成一个v20.10.0的文件夹，里面存放了对应版本的nodejs的所有文件。
使用 nvm use 20.10.0
当初安装nvm时指定的Nodejs的目录，实际上是一个软连接，指向了你正在use的nodejs的版本文件夹。
验证 node -v, npm -v
配置Nodejs

设置npm镜像源：npm config set registry https://registry.npm.taobao.org
配置全局目录：
先在Nodejs目录下手动创建node_global目录和node_cache目录，然后执行：
npm config set prefix "D:\my_apps\for_produce\Nodejs\node_global" npm config set cache "D:\my_apps\for_produce\Nodejs\node_cache"
上述命令解释
1. 将 npm 的全局安装目录设置为指定的路径。这样，我们在安装全局模块时，它们会被安装到这个目录下。（全局安装是指不把包安装在特定项目中，而是所有项目可用）。
2. 将 npm 的缓存目录设置为指定的路径，用以存储下载的包和资源的位置。
把全局目录加入环境变量
只有把目录加入了环境变量，你用npm全局安装的那些包/工具才能在任意位置被使用。如hexo命令。
方法为：在系统环境变量的path中添加：%NVM_SYMLINK%\node_global。然后重启计算机。

nodejs的包管理
用npm进行管理，如全局安装cnpm(指定源)：npm install -g cnpm --registry=https://registry.npm.taobao.org

全局安装了hexo博客工具

npm install -g hexo-cli

创建一个博客源码仓库

~ 如果你只想在本地搭建博客，没有远程管理及迁移的需求，可跳过该节。

在github/gitee新建私有仓库blog-source, 克隆到本地;

进入blog-source目录，制作.gitignore:

.DS_Store
Thumbs.db
db.json
*.log
node_modules/
public/
.deploy*/
_multiconfig.yml

然后进行下节的博客搭建工作。
当需要上传博客源码时：git add --all && git commit -m "update" && git push origin main。

如果是gitee, main要换成master

本地搭建

s1-造目录

如果你没有在上一节创建仓库，则直接创建空的博客工程目录 blog-source；
如果有了仓库，则克隆下来git clone your_repo_url.git

s2-搭框架

如果是从零开始，则进入空目录，用命令hexo init来初始化得到博客框架；
如果已有博客，想移植其他主题，则建议按需移植以下目录/文件过来：
- scaffolds/ # 模版 - source/ # 各种文章内容、资源 - themes/ # 主题 - _config.yml # 配置文件 - _config.theme.yml - package.json ...
为什么不整个移植过来呢？因为其他目录/文件都是通过上述目录/文件生成的，保证了移植时的轻量化。

s3-装软件

安装‘package.json’中的npm依赖，执行npm install。

s4-配主题

如果对stellar主题功能更新没有兴趣，直接安装稳定版：npm i hexo-theme-stellar
如果想跟随stellar作者的更新脚步，则克隆他的主题仓库，
- 若当前目录下有.git/，即已经把博客工程设为一个git仓库，那就用git的子模块：
- 若没有，那就用：
如果想时时更新，还有自定义需求，那就fork他的仓库到自己的GitHub，然后用上面的clone或submodule add命令即可；
然后在_config.yml中修改：theme: stellar。

以后如果主题有更新，则先同步fork，后进入themes/stellar/,执行git pull即可。

s5-DIY主题

先将主题目录下的config文件复制到根目录下，使得hexo可用：
然后可选择进一步根据stellar官方教程或我的主题手册设计自己的网站。

s6-写文章

此刻你已经可以创建、修改、部署博客到本地了，常用命令有：

hexo new post [title] (新建文章)
hexo clean && hexo g && hexo s (清缓存、生成网页、本地部署)

我的另一篇文章主题手册是对stellar官方教程的总结，用以辅助写文章。我也将时刻关注主题版本的升级，新内容都将同步添加到我的主题手册中。

部署博客到互联网

最简单快捷：部署到GitHub/Gitee

新建公有仓库，存放我们的输出的网页静态文件（即hexo g命令后生成的/public/文件夹）

仓库名有讲究：GitHub应为用户名.github.io; Gitee应为用户名

将仓库加入配置

./_config.yml

deploy:
- type: git
  repo: [email protected]:jamesray0713/jamesray0713.git
  branch: master
  message: "update"
- type: git
  repo: https://github.com/JamesRay0713/JamesRay0713.github.io.git
  branch: gh-pages
  message: "update"

注意GitHub和gitee两者branch的区别

下载部署工具: npm i hexo-deployer-git
执行部署：hexo clean && hexo g && hexo d
仓库开启服务
github
gitee
在仓库的Settings设置中找到Pages选项卡，设置Source和Branch为如下图所示：

此时，我们得到了域名user.github.io。
在仓库的服务下拉中找到Gitee Pages选项卡，可以什么都不要动，只需点击更新即可。
此时，我们得到了域名user.gitee.io。

更好的部署：购买域名+ vercel部署

Vercel可以获得更快的访问速度，但在大陆地区vercel.app和github.io均被运营商进行了DNS污染，无法直接访问。因此需要购买域名。

准备域名：
- 购买域名: 我在腾讯云上买了taddream.site，有效期10年，￥175，挺实惠的。
- 备案域名:
  需要备案的场景：你的存放静态文件的服务器在国内，我目前托管在vercel完全没必要的。
  如果你的网站有很大的访问流量，建议把服务器搬到国内。
  这里服务器有两种情况：
  - 购买的云服务器：按照官方教程走即可
  - 自己的实体服务器：该情况下备案审核要求很繁琐（特别是腾讯云），而且需要有营业执照+ 备案授权码
    
    营业执照那里需填写法人身份信息，你得自己想办法；
    授权码可以去淘宝搜‘腾讯授权码’，10块左右。
- 设置DNS解析：在云服务商的域名DNS解析中增加2条CNAME 解析, 主机记录分别是@、www：
  
  主机记录记录类型记录值 TTL 解析请求来源(isp)
  
  @ CNAME cname.vercel-dns.com 10分钟默认
- 获取免费SSL证书，一年一签。
  
  免费证书局限性：不支持二级域名，如mail.taddream.site; 收费证书真的好贵，600+。
vercel.com部署：
用GitHub账号登录，Add New... -> Project, 导入我们的静态文件仓库（username.github.io）。
输入projectName，这直接关系到三级域名的名字，点击部署。
修改分支：因为我们的博客静态文件存到了gh-pages分支，所以在当前vercel项目中依次点击settings -> git -> Production Branch, 输入gh-pages即可。

分支不会立即生效，需再次用hexo d将静态文件部署上传后，这里才能自动更改。
此时，我们得到了新域名taddream.vercel.app(国内不可访问)。
绑定域名：
在当前vercel项目中依次点击settings -> Domains -> Production Branch, 填入我的域名taddream.site
修改博客配置文件, 修改之后需等待重新部署后生效：
./_config.yml
url: https://taddream.site

主机记录	记录类型	记录值	TTL	解析请求来源(isp)
@	CNAME	cname.vercel-dns.com	10分钟	默认

github自动化部署(TODO)

TODO：　https://hexo.io/zh-cn/docs/github-pages

借助GitHub Actions实现自动化。我们无需再负责维护user.github.io仓库, 只需push好源码仓库即可。
gitee无自动化功能，考虑放弃gitee部署这条路。

我们直接在本地源码仓库目录的.github/workflows/下创建配置文件(即自动化脚本)，如下：

.github/workflows/auto-deploy.yml

name: auto deploy
on:
  workflow_dispatch:  # 手动触发
  push:               # push代码时触发
jobs:
  build:
    runs-on: ubuntu-latest # 运行环境为最新版 Ubuntu
    name: auto deploy
    steps:
    # 1. 获取源码
    - name: Checkout
      uses: actions/checkout@v3 # 使用 actions/checkout@v3
      with: # 条件
        submodules: true # Checkout private submodules(themes or something else). 当有子模块时切换分支？
    # 2. 配置环境
    - name: Setup Node.js 18.12.x
      uses: actions/setup-node@master
      with:
        node-version: "18.12.x"
    # 3. 生成静态文件
    - name: Generate Public Files
      run: |
        npm i
        npm install hexo-cli -g
        hexo clean && hexo generate
    # 4. 部署到 GitHub 仓库（可选）
    - name: Deploy to GitHub Pages
      uses: peaceiris/actions-gh-pages@v3
      with:
        deploy_key: ${{ secrets.DEPLOY_KEY }}
        external_repository: JamesRay0713/JamesRay0713.github.io
        publish_branch: gh-pages
        publish_dir: ./public
        commit_message: ${{ github.event.head_commit.message }}
        user_name: 'github-actions[bot]'
        user_email: 'github-actions[bot]@users.noreply.github.com'
    # 5. 部署到服务器（可选）
    - name: Deploy to Server
      uses: easingthemes/ssh-deploy@v3
      env:
        SSH_PRIVATE_KEY: ${{ secrets.SERVER_SSH_KEY }}
        ARGS: "-rltgoDzvO --delete"
        EXCLUDE: ".well-known, .user.ini"
        SOURCE: public/
        REMOTE_HOST: ${{ secrets.REMOTE_HOST }}
        REMOTE_PORT: ${{ secrets.REMOTE_PORT }}
        REMOTE_USER: ${{ secrets.REMOTE_USER }}
        TARGET: ${{ secrets.TARGET }}

选择仅部署GitHub时，只需修改其中external_repository为自己的博客静态文件仓库

配置公私钥，用于’Action的虚拟机(客户端，私钥)’同’静态文件仓库(服务端，公钥)’的通信：
- 准备一对公私钥(方法)
- 放置公钥：进入external_repository→ settings→ Deploy keys→ Add Deploy key

更高级部署：用自己的服务器

略，以后探索。参考：

https://zhuanlan.zhihu.com/p/120743882

网站进一步优化

（参考以补充该部分内容）

使用图床

关于图床服务和图床工具

图床服务，如七牛云，是一种为用户提供图像存储和分享的便利平台。图床能提高博客站点的性能、稳定性，并简化博客的管理和维护。
图床工具，如PicGo，简化了图片上传和链接生成的流程，提高了效率，尤其对于需要频繁上传图片的场景。

为什么要用图床服务

加快页面加载速度：是将博客页面中的图片资源托管到专门的图片服务器上，从而减轻博客服务器的负担。
节省博客服务器存储空间：不再把图片放在博客目录的/assets/下了。
避免博客迁移和备份问题
提高图片访问稳定性
支持防盗链：图床服务通常支持防盗链功能，可以限制图片只能在特定域名下显示，防止图片被其他网站直接引用，避免了大量的流量和费用。

为什么要用图床工具`PicGo`

快速上传和生成链接
多图床支持： weibo, qiniu, tcyun, upyun, github, aliyun, imgur and SM.MS
Markdown图片链接自动生成：简化插入图片的过程
丰富的配置
本地图片处理功能：如裁剪、压缩等
跨平台支持：支持多个操作系统
插件系统：通过安装插件来扩展 PicGo 的功能

图床服务1：七牛云(含免费)

使用七牛云中的对象存储服务，￥60/50G/年。

资料：
开发者文档，含图像处理API
优缺点：
- 优点：有免费额度：对象存储10G/月+ CDN加速10G/月；有丰富的图像处理API，可满足缩放、裁剪等。
- 缺点：免费只针对HTTP服务，HTTPS的图片链接要收费。但是大多数浏览器会拦截这些非安全（非 HTTPS）的资源，导致无法加载图片。

完整的搭建步骤

I. 建立一个图床空间：登录/注册进入控制台 -> 对象存储Kodo -> 空间管理 -> 新建空间

如果你的图床空间主要用于服务你的博客网站, 而你的博客域名未在国内备案，那么存储区域就要选海外的；
访问控制选公开。
II.给空间绑定域名：
七牛云默认给空间绑定了临时的CDN加速域名，有效期30天，若想自定义绑定域名，有以下途径：
- 自定义CDN加速域名：我没购买过，pass，以后探索（TODO）；
- 自定义源站域名：刚好可以用我的博客域名，bingo。在经历bug和debug后，我选择默认HTTP+子域名的方式。
  
  番外篇：bug与debug的经历
  起初我想当然地把域名绑定成了我的主域名(taddream.site)，并在域名中添加了七牛给我的CNAME值，并对该绑定配置了HTTPS。
  结果就是当访问带主域名的图床外链(如https://taddream.site/img/xxx.jpg)，甚至访问主站（taddream.site）时，浏览器就会报错不安全的连接，有时稍等几分钟即恢复正常；有时完全不恢复。
  我认为原因是：域名的原有解析记录、和新建的七牛的解析记录打架了。
  因此需要用子域名来七牛的CNAME。

继续正题，绑定域名步骤如下：

点击进入空间名 -> 域名管理 -> 自定义源站域名 -> 绑定域名，绑定时输入assets.taddream.site(这里assets改成你喜欢的)；
复制CNAME值：形如iovip-as0.qiniuio.com
给域名添加七牛的解析记录：进入域名服务商的域名管理列表 -> 点击进入博客域名 -> 记录管理 -> 添加记录，进行如下配置：

主机记录记录类型记录值其他

assets CNAME iovip-as0.qiniuio.com 默认
可选步骤：配置HTTPS：
如果你的子域名(assets.taddream.site)没有SSL证书，那就略过，直接使用不安全的http；如果有，那就配置，方法如下：
- 从域名服务商下载证书：进入我的ssl证书 -> 下载关于博客域名的pem格式证书 -> 解压
- 上传证书到七牛：进入证书管理 -> 上传自有证书 -> 按提示上传刚解压的证书内容、证书私钥
- 点击配置HTTPS -> 更换证书
可选步骤：增加图片镜像缓存服务，即在你未来的图像url前面加上镜像url, 如https://images.weserv.nl/?url=assets.taddream.site/your_image.png

主机记录	记录类型	记录值	其他
assets	CNAME	iovip-as0.qiniuio.com	默认

III. 给空间加防盗链：点击进入空间名 -> 空间设置 -> Referer 防盗链 -> 设置开启状态 -> 在白名单中加入自己的博客地址和常用搜索引擎 -> 允许空 Referer
- 白名单：*.taddream.site, *.baidu.com, *.bing.com, *.google.com
- debug: *.taddream.site放入白名单仍会得到forbidden 403的问题，见。
IV. 测试效果：上传一张图片到空间即可得到该图片的图床链接（链接的外链域名可以是我们绑定的博客子域名、也可以是七牛默认的CDN域名）。
V. 如果想让本地层级目录整个迁移到图床空间呢
使用qshell同步本地文件目录到存储空间并体现出层级结构，参考文档1、文档2。以下是教程总结：
- 下载：下载win_x64的执行文件；
- 安装：解压，把.exe文件放到自定义目录，将该目录添加环境变量，这样，在cmd中就可使用qshell命令了；
- 添加账户：qshell account ak sk 自定义名字；查看账户：qshell user ls
  
  这里的ak, sk在这里找。
- 配置：在~\.qshell\upload.conf中添加需要迁移的本地目录
  { "src_dir" : "H:\\blog_space\\hexo_arch\\blog-assets", //这里七牛云是将`assets`作为了‘blog-dream’空间的根目录。 //"ignore_dir" : true, "bucket" : "blog-dream" }
- 执行迁移命令：qshell qupload ~\.qshell\upload.conf，完成。

拓展：七牛图像处理API

七牛图床可以通过http://assets.taddream.site/<图像名>?<处理接口>的方式，实现裁剪、缩放、调色等操作。文档见：开发者中心->智能多媒体服务->API文档->图片处理

可视化设计接口：进入空间 -> 图片样式 -> 新建图片样式
示例场景：
- 居中裁剪出高度为100的图片：http://assets.taddream.site/my-best-avatar.png?imageMogr2/gravity/Center/crop/x100/blur/1x0/quality/75

图床工具：PicGo

它的主要功能：我们前端在编写md文档时，直接粘贴图片、或选择路径上传图片，就能得到md格式的图片链接。工具后端自动将我们选好的图片上传到图床服务商，然后返回链接，呈现在md文档中。
资料：源码，picgo-core文档, picgo文档
可以使用版本：UI软件版；VScode插件版。

这里我只探索了VScode插件版:

配置方法如下：

picgo.picBed.uploader: 选择你的图床服务商，我选择了qiniu

picgo.picBed.qiniu: 该模块下的相关配置参考下面，这里的前提是已经在相应服务商做好了图床空间的各种设置。

{
  "accessKey": "",        //在 https://portal.qiniu.com/developer/user/key 查找
  "secretKey": "",
  "bucket": "blog-dream", // 存储空间名
  "url": "http://assets.taddream.site", // 自定义域名，一定要带上协议头。
  "area": "as0", // 存储区域编号  "z0" | "z1" | "z2" | "na0" | "as0"
  "options": "", // 网址后缀，比如 `?imgslim`。网址后缀通常是你用到了七牛的图片处理工具的时候会用到的一些处理参数，比如图片瘦身。
  "path": "" // 自定义存储路径，比如 `img/`
}

注：path的字符串，尾字符须为/，且首字符为/时无效，字符串内部有/则表示添加了一个父目录。
当你想使用快捷键上传图片到图床的指定目录时，记得随时在这里修改path。

picgo.customOutputFormat: 自定义上传图片的输出格式，如

"picgo.customOutputFormat": "<img src=\"https://images.weserv.nl/?url=${url.replace('http://', '')}\" alt=\"${uploadedName}\" width=\"80%\"/>",  
// 这里我把格式设为html的<img>标签样式，同时增加了图片镜像缓存服务。
// 或者 "picgo.customOutputFormat": "![${uploadedName}](${url})"

其他的就按你所需来配置。

使用方法如下：
- step1: 把光标放在你要插入图片的地方，或选中一些文字（选中的文字就是图片别名，若没有，则图片文件名就是图片别名）；
- step2: 方法1：复制本地图片到剪切板，在光标处按下Ctrl + Alt + U，完成！
- step2: 方法2：在光标处按下Ctrl + Alt + E，手动选择本地图片，确认后完成！
  
  图床可存放的资源可不仅限于图片，也包括视频、音频、文档、二进制文件等，均可如上炮制。最后只需把生成的那个叹号删掉，就变成了非图片资源的超链接了。

图床服务2：Cloudflare Pages+Telegraph

资料：戳
该方法借助在Cloudflare搭建图床服务，实现彻底的白嫖。教程总结如下：

搭建图床网站：fork项目 -> 进入 cf-pages面板 -> Workers和Pages -> 概述 ->
- 先创建应用程序 -> Pages -> 连接到Git -> … -> 选择刚刚fork的仓库
- 后进行相关配置并部署，可全都默认，直接保存并部署 -> 最终得到了自己的图床服务网站，见https://telegraph-image-1ei.pages.dev/
  
  也可按提示自定义域名。
管理图床网站：
- 添加命名空间：Workers和Pages -> KV -> 创建命名空间 -> 起个名字(如blog-assets2) -> 添加；
- 绑定命名空间：Workers和Pages -> 概述 -> 进入项目telegraph-image -> 设置 -> 函数 -> KV命名空间绑定 -> 添加绑定 -> 变量名称只能写img_url、KV命名空间选择上步添加的blog-assets2 -> 保存；
- 给图床制作用户和密码：Workers和Pages -> 概述 -> 进入项目telegraph-image -> 设置 -> 环境变量 -> 添加变量并保存:BASIC_USER,BASIC_PASS, 其值可完全自定义；
- 重新部署图床网站:
- 进入管理界面：Worker域名/admin登录即可，如 https://telegraph-image-1ei.pages.dev/admin