这篇笔记记录如何将本地生成的静态站点上传到七牛云对象存储，并通过 CDN 和自定义域名访问。内容从旧站迁移而来，命令已按当前 Astro 项目和新版 qshell 调整。
Table of contents
Open Table of contents
准备七牛云账号和 Bucket
如果是新用户，先在七牛云门户注册账号并完成实名认证，然后进入对象存储空间管理创建一个 Bucket。
创建时需要确认：
- Bucket 名称：后面上传命令会用到。
- 存储区域：选择离主要访问用户较近的区域。
- 访问权限：静态网站通常需要公开读取，或者通过已正确配置的 CDN 域名访问。
本文统一用 <BUCKET_NAME> 表示实际的 Bucket 名称，避免把个人配置写死在文章中。
安装并配置 qshell
从七牛官方的 Qshell 文档下载适合当前操作系统的版本。macOS 或 Linux 下载后，可能需要增加执行权限：
chmod +x qshell确认工具可以运行：
qshell -v上传操作需要 AccessKey 和 SecretKey。可以在七牛云密钥管理中查看，然后执行：
qshell account <ACCESS_KEY> <SECRET_KEY> <ACCOUNT_NAME>ACCOUNT_NAME 是本地保存的账号别名，可以自行设置。
不要把真实的 AccessKey、SecretKey 写进 Markdown、脚本、Git 仓库或截图。若密钥已经泄露，应立即在控制台轮换。
可以使用下面的命令查看或切换 qshell 保存的账号：
qshell user ls
qshell user cu <ACCOUNT_NAME>构建 Astro 静态站点
进入当前 portfolio 项目：
cd /Users/selfknow/blog/portfolio执行正式构建：
pnpm build构建成功后，待上传的静态文件位于：
dist/上传前可以先用本地预览检查页面：
pnpm preview重点确认文章页面、图片、数学公式、搜索和静态资源都能正常访问。
上传 dist 目录
七牛当前优先推荐使用 qupload2 批量上传目录，不必再单独维护旧版 upload.conf：
qshell qupload2 \
--src-dir=./dist \
--bucket=<BUCKET_NAME>需要查看当前版本支持的完整参数时，直接执行：
qshell qupload2 --doc再次部署时，qshell 会根据文件状态处理上传。需要严格删除 Bucket 中已经不再存在于本地的旧文件时，应先确认删除范围，再单独处理远端对象；不要未经检查就执行批量删除。
开启默认首页
进入七牛云控制台的 Bucket 设置，开启默认首页功能。这样访问目录路径时，服务才能正确返回相应的 index.html。
完成上传后，可以先通过七牛提供的测试域名检查：
- 首页是否能够打开；
/posts/.../这类目录路由是否返回页面；- CSS、字体和图片是否正常加载；
- 404 页面是否符合预期。
测试域名适合验证，不适合作为长期公开地址。
配置 CDN 和自定义域名
在七牛云控制台为 Bucket 添加 CDN 加速域名，并按照控制台给出的目标配置 DNS CNAME。
基本流程如下：
- 准备一个可用的自定义域名。
- 在七牛云中将该域名绑定到对应 Bucket。
- 到域名的 DNS 服务商处添加七牛提供的 CNAME 记录。
- 等待 DNS 和 CDN 配置生效。
- 使用自定义域名检查站点。
如果域名用于中国大陆节点，通常还需要满足 ICP 备案等要求，具体以域名、区域和七牛控制台提示为准。
配置 HTTPS
可以在七牛云的证书管理中购买或上传证书，再为 CDN 域名启用 HTTPS。
上传自有证书时，按照控制台要求准备证书链和私钥。开启 HTTPS 后，检查：
curl -I https://<YOUR_DOMAIN>/还要在浏览器中确认没有 HTTP 图片、脚本或字体造成的混合内容问题。
部署后的检查
每次上传完成后，至少验证：
- 首页、文章列表和一篇文章详情；
- CSS、JavaScript、字体和图片；
/search/与 Pagefind 索引；- RSS、sitemap 和 robots.txt；
- 自定义域名的 HTTPS 证书；
- 新旧文件是否受到 CDN 缓存影响。
如果页面仍显示旧内容，可以在七牛 CDN 控制台执行缓存刷新，再重新检查。
当前项目的最短部署路径
在账号、Bucket、域名和 HTTPS 都已配置完成后，日常发布主要是两步：
pnpm build
qshell qupload2 \
--src-dir=./dist \
--bucket=<BUCKET_NAME>对象存储只负责托管构建产物。文章源文件、站点配置和密钥仍应分别管理：Markdown 与代码进入 Git，dist/ 由构建产生，AK/SK 不进入仓库。