AI 与技术通识 · 个人知识站
第 9 课:部署上线,让别人真正能打开你的网站
用本仓库已本地验证兼容的 Cloudflare Pages 静态导出教学路线发布网站,检查路由、内容、资源和承接入口。
你现在真正要解决的问题
你在自己的电脑上打开了首页,文章也能读;发给朋友一个 localhost:3000,对方却无法访问。原因不是朋友网络有问题:localhost 指向当前正在使用的那台设备,互联网用户需要一个能够公开解析的地址和托管网站文件的服务。
部署不是按下一个“发布”按钮就结束。代码要先构建成主机可以提供的文件,再上传到公开托管平台;然后逐条检查页面是否直接可访问、图片和样式是否加载、深层链接刷新是否正常、联系入口是否真的有效。本课采用一条已在本地验证兼容的 Cloudflare Pages 静态部署教学路线:Next.js 静态导出 → GitHub → Cloudflare Pages → *.pages.dev 公共地址。这只说明当前项目的构建产物符合该静态托管路线,不表示 LUPY 线上生产环境正在使用 Cloudflare Pages。本课教操作步骤,但不会替你推送代码、部署或更改线上站点。
关于“当前 LUPY 到底部署在哪里”的证据边界:仓库的 next.config.ts 和生产构建能直接确认项目兼容静态导出;SECURITY-CLOUDFLARE.md 记录 GitHub → Cloudflare Pages 的部署链路;但 DEPLOYMENT.md 仍写“推荐 Vercel”。仓库中没有 Cloudflare Pages、Vercel、Wrangler 或 GitHub Actions 的部署配置文件,GitHub remote 只说明源码远端,不说明部署平台。对公开域名的只读请求返回 Server: cloudflare 和 Cloudflare 边缘响应标识,只能证明请求经过 Cloudflare 网络代理;它不能证明源站就是 Pages,也不能排除 Vercel 等源站位于代理之后。因此无法仅凭现有证据确认 LUPY 线上真实托管平台。本课保留可由本地静态构建结果和 Cloudflare 官方文档核实的 Pages 教学路线,不声称它就是 LUPY 当前线上方案,也不替仓库消解文档冲突。
这一课完成后,你会得到什么
- 一个公开可访问的
https://{项目名}.pages.dev/地址;若账号验证或平台可用性受限,保存明确阻塞记录。 - 一次与 Git commit 对应的构建与部署记录。
- 一份可以逐项执行的上线检查清单和故障排查顺序。
- 一条内容修改、预览、验收、提交并重新发布的最小流程。
先看全局:代码经过哪些门才能成为公开页面
部署指将构建产物交给托管平台提供给访问者。构建是运行项目构建命令,将源码检查并生成可部署文件的步骤。本仓库的 next.config.ts 设置了 output: "export" 和 trailingSlash: true,所以 npm run build 调用 Next.js 生成静态站点到 out/。本地开发服务器中的源码和公开站点中给浏览器读取的静态文件不是同一批文件。
| 状态 | 能证明什么 | 不能证明什么 | 此时检查 |
|---|---|---|---|
| 本地成功 | 开发环境能运行源码,浏览器能连接本机服务器 | 构建服务器兼容、公开地址有效、其他网络能访问 | 文章详情、资源、按钮、手机布局 |
| 构建成功 | Next.js 在当前构建环境成功生成产物,进程以成功状态退出 | 平台上传成功、域名解析成功、页面真实可读 | out/index.html、深层路由目录、构建日志和 commit |
| 公开可访问 | 访问者能通过 HTTPS 公网 URL 读取已发布文件 | 每个页面都正确、表单被接收、业务承诺可交付 | 深层 URL、刷新、链接、图片、CTA、窄屏 |
贯穿案例推进:把个人知识站公开但不暴露秘密
本例的项目已经在本地显示首页,src/content/guides/ 中有文章和课程,src/data/systems.ts 组织课程顺序。第 8 课的承接页目前是一张静态说明,没有自动收集资料或付款功能。发布前,先在本地构建,把 out/ 看成将公开的全部内容:里面的 HTML、脚本和图片任何人都可下载。.env.local 即使放了未使用的测试密钥,只要误复制进 public 或直接写进页面,最后仍可能泄露;而一旦浏览器端代码引用的变量被打包,它就不再是秘密。
| 部署前后 | 项目处于什么状态 | 应做的决定 |
|---|---|---|
| 部署前 | 仅你本机能访问;课程和文章文件还在 Git 工作区中 | 先确认自己有权公开所有文案、图片和代码;删掉私密草稿与占位联系信息 |
| 首次发布 | GitHub 保存某个 commit;Pages 用该 commit 构建并给出公开 URL | 记录 commit、构建结果和 URL;先用 pages.dev,域名不是前置要求 |
| 验收完成 | 公开页面可读,路由和入口都按文字预期工作 | 只有验收通过才将网址分享;问题先修复并重新构建 |
| 后续维护 | 内容每次更新都会再次构建;可通过新 commit 发布 | 一次更新一次验证,保留变更提交作为回退依据 |
跟着做:从本地构建到 Pages URL
第一步:确认项目真的是可静态导出
**做什么:**打开 next.config.ts,确认项目对外输出模式是 output: "export",再看 package.json 的 build 脚本。**为什么现在做:**Cloudflare Pages 将静态文件托管到边缘;它不会替普通 Pages 项目运行完整 Next.js Node 服务器。**输入:**当前 LUPY 配置还包含 trailingSlash: true,会让路径映射到 out/{route}/index.html。自己的初始项目若没有这些设置,在 next.config.ts 的配置对象中加入 output: "export",保留原有必要配置;不要覆盖整份配置。正常结果:npm run build 完成后生成 out/index.html 和内容详情页面目录。**出错先检查:**搜出依赖 Node 运行时的 API、动态请求、Middleware、需要运行时身份验证的功能,或默认图片优化配置;这些不适合静态导出,需要换成静态资源/外部服务或重新设计。
静态导出在构建时为各个可确定的路由生成文件,没有线上 Node 服务器替你读取实时数据库或处理 POST 表单。动态段需要在构建阶段列出可以生成的参数;当前课程页面在构建时由本地 MDX 文件和课程章节清单生成。读者提交表单不能直接写进静态 HTML:应链接到真实第三方服务,或者在另一阶段设计后端。不要把静态站说成已有服务器表单。
第二步:本地构建和检查输出
**做什么:**先运行 npm run lint、npm run build。**为什么现在做:**在推送前发现语法、TypeScript、frontmatter 或静态路由问题更容易定位。**输入:**在项目根目录的终端执行:
npm run lint
npm run build
**正常结果:**两个进程退出码为 0;构建输出包含路由清单;资源位于 out/。检查 out/index.html,并对照一个文章和一个课程目录,例如 out/learn/personal-site-07-library/index.html。**出错先检查:**第一条真正的错误而不是日志末尾;错误来自 lint、MDX 解析、静态参数还是远程资源。网络字体下载失败可能只是 warning 或构建失败,依据最终退出码判断;优先使用项目已保存的本地字体,不要在错误状态下继续发布。
本仓库使用 npm,部署环境应使用仓库已有 package-lock.json 锁定依赖版本。你在 Cloudflare Pages 的 build 配置选择与 lockfile 匹配的 npm 安装方式;框架预设会根据 Next.js 静态导出配置构建,若需手工填写,npm run build 等价于执行 next build。构建命令必须实际以 exit code 0 结束,不能只看日志出现“compiled”。
第三步:清理准备公开的内容,保存一个提交
**做什么:**检查 Git 更改,确保公开版本内容齐全,并建立清晰的发布检查点。**为什么现在做:**GitHub 和托管平台都能读取仓库里已提交的代码;不希望出现在网站的文件不要推送。**输入:**在本地运行 git status、git diff --check、git diff;检查 .gitignore 排除 .env*(保留 .env.example)、node_modules、.next 和 out。**正常结果:**本地 build 通过,diff 里只有你知道用途的项目文件,commit 信息能对应本次发布。**出错先检查:**不要把密钥复制到示例环境文件;如果本应忽略的文件已经暂存,先从暂存区移出、修复 .gitignore 并确认历史中从未公开。
out/ 是生成产物,通常让 Pages 在云端根据源码重建,而不是把它和源码一起提交。课程项目里,执行 git add 前先逐个检查变更;提交成功后用 git log -1 --oneline 记录 commit 短哈希。GitHub 仓库设私有或公开由你按代码许可证和隐私决定;即使是私有代码,发布到公开 URL 的网页内容仍是公开的。
第四步:创建 GitHub 远端并推送
**做什么:**在 GitHub 网页创建一个新的空仓库,再把本地仓库连接过去。**为什么现在做:**Cloudflare Pages 的 Git integration 读取远端分支并在更新时构建。**输入:**创建时不要勾选添加 README、License 或 .gitignore(本地已有 Git 历史);复制仓库 HTTPS 地址,然后在项目根目录执行:
git remote add origin https://github.com/{你的用户名}/{你的仓库名}.git
git branch -M main
git push -u origin main
花括号部分替换成 GitHub 实际用户名与仓库名,命令中保留 .git。若已有 origin,用 git remote -v 查看,不要再添加同名 remote;远端已有 README 时先停下确认仓库状态,不要强推覆盖。**正常结果:**GitHub 仓库页面显示预期 commit 和源代码。**出错先检查:**登录状态、仓库 URL、分支保护、GitHub 权限或 HTTPS 凭据;不要把 access token 写进命令文本、截图或仓库配置。
第五步:在 Cloudflare Pages 配置 Git 集成
**做什么:**在 Cloudflare Dashboard 的 Workers & Pages 中创建 Pages 项目,连接 GitHub 并选择上一步的仓库。**为什么现在做:**后续把一个审核过的 commit 推到生产分支,Pages 就可重复执行同一构建。**输入:**选择 Next.js (Static HTML Export) 预设,核对生产分支 main、构建命令 npx next build、构建目录 out;或按该仓库 package.json 用 npm run build,两者都执行 Next 构建。根目录是仓库根 .,只有 monorepo 才改。设置 Node 版本与本地一致并满足当前 Next.js 最低要求,例如添加根目录 .nvmrc,内容填项目团队确认的版本。**正常结果:**日志显示安装依赖、运行构建、上传 out;平台提供项目的 pages.dev URL。**出错先检查:**部署面板是否选错 Framework preset、根目录是否选到空目录、锁文件与包管理器是否匹配、Node 版本是否低于要求。
平台界面可能调整名称或布局;步骤中的配置值来自代码和官方静态 Next.js 预设,不来自猜测按钮位置。免费 Pages 方案当前可生成 pages.dev 公开地址,不要求先购买自定义域名;账户是否需要额外验证受平台当时政策和地区影响,若控制台要求某项验证,应按实际提示决定是否继续,不要输入课程无法核实的付款或身份信息。不要把套餐限额写成永久不变的承诺。
第六步:读构建日志,而不是看一行红色提示就重装
Pages 日志可按环节区分。示例:
Installing project dependencies ... done
Executing user command: npm run build
Type error: Cannot find name 'OfferPage'
Failed: build command exited with code: 1
第一行说明依赖安装结束;真正错误是 TypeScript 找不到 OfferPage;exit code 1 说明构建未成功,因此没有可用的本次部署产物。回到本地对应文件修正名称、运行 lint/build,再提交新改动。若日志在 Installing dependencies 停止,检查 package-lock、网络和 npm;若静态参数阶段报告缺少 slug,检查课程文件是否已经在本次 commit 中、slug 是否有效;若 upload 阶段失败而 build 通过,检查产物目录和平台状态。不要把警告误当成功,也不要忽略 exit code。
第七步:从外网按访问者方式验收
**做什么:**用无痕窗口或另一台设备直接粘贴公网链接;不要只点站内链接。**为什么现在做:**直接进入深层地址和刷新会揭示路由与资源路径错误。**输入:**逐项打开首页、/learn/、一个系统目录、至少一篇课程/文章详情、站点地图和 robots 文件;刷新深层页面并测试内部链接、图片、字体和行动入口。**正常结果:**HTTPS 锁标识有效,公开页无构建占位文字,详情页可直达且刷新后仍正常,CTA 目标与页面说明一致,手机宽度可读。**出错先检查:**先比较 pages.dev 和自定义域名;前者通而后者不通多半是 DNS/域名配置,不要重建全部内容。
| 上线验收项 | 操作 | 通过证据 |
|---|---|---|
| 公网首页 | 无痕窗口访问 https://{项目}.pages.dev/ | 返回页面且 HTTPS 无证书警告 |
| 深层课程/文章路由 | 直接粘贴含路径的 URL,刷新 | 仍返回对应页面,不只从首页点击能打开 |
| 样式与资源 | 检查 CSS、图片、字体、图标 | 无 404、破图、未样式化正文 |
| 目录与导航 | 从首页进入栏目,再用浏览器返回 | 导航目标有内容,上一课/下一课顺序正确 |
| 手机视口 | DevTools 选窄屏,向下检查 | 无横向溢出、遮挡、文字裁切 |
| CTA | 实际点击邮件、第三方表单或购买链接 | 目的地、提交字段和后续流程符合旁边说明 |
| 私密信息 | 查看仓库与部署页面中的公开资产 | 没有 token、未授权图片、私密草稿或占位邮箱 |
| 发布记录 | Pages 页面查看生产 commit 和日志 | commit 哈希与本地验收记录对应 |
第八步:可选绑定自定义域名并理解回滚
pages.dev 已经是公开网址,可以完成课程目标。自定义域名是独立购买和配置的地址升级,不是部署前置条件。根域通常需要将域名添加为 Cloudflare zone 并配置 nameserver;子域通常添加 CNAME 指向项目的 pages.dev 地址。先在 Pages 项目中完成“添加自定义域名”流程,再按面板要求配置 DNS;只在 DNS 随便加一条 CNAME 而没先关联 Pages,可能导致验证错误。DNS 是把域名映射到服务地址的一组记录;传播会有延迟,不等于构建失败。
上线后回滚是让访客回到一份已知可用的发布版本。先在 Pages 部署列表找到上一份验收通过的 commit,并记录当前故障提交;优先修复后经 Git 推送新版本。若必须立刻恢复,按平台当前部署回滚能力回到前一部署,并在本地保留故障记录,不删除 Git 历史。对静态项目,最稳的可重复方式是使用 Git revert 生成反向提交,再由 Pages 正常构建;团队应遵守仓库已有审查流程。
你现在应该看到什么
电脑和手机浏览器都能打开一个 HTTPS 公共网址;直接访问首页和一个深层内容 URL 均能加载。Pages 的部署日志显示构建成功,并关联你刚才记录的 commit;out/ 结构与 trailingSlash 路径相符。你的公开页面没有需要保密的环境变量,也没有宣称静态网站已经处理支付或表单数据。
本课任务与提交物
- 保存
docs/deployment-record.md:写项目配置、commit 短哈希、本地构建命令和真实结果、Pages 部署日期、生产 URL、日志链接或截图。 - 在
docs/launch-checklist.md保存并完成上方验收表;至少从外部网络直开一篇深层内容。 - 公开部署当前课程项目,或将
pages.dev页面暂时受阻的真实原因记录在docs/project-status.md,例如账户未完成验证、无 GitHub 权限;不虚构已上线。 - 保存
docs/deploy-troubleshooting.md:按“本地配置 → commit → 依赖安装 → build → 输出目录 → 上传 → URL/DNS”顺序写排查结果。 - 演练一次最小更新流程:本地改一条真实文字、lint/build、检查差异、commit、推送,然后在 Pages 查看新部署日志和公开页更新。此为课程动作,由学习者操作。
自检清单
- 项目静态导出设置与本地构建输出
out/相符。 - 生产分支指向预计的 Git 分支,Pages 项目选的是正确仓库。
- 本地 lint/build 均成功,日志里构建命令返回成功码。
-
pages.dev首页与深层路由可直接打开和刷新。 - 文章、课程目录、资源、站点地图与 CTA 都经过公网访问检查。
- 静态公开文件没有密钥、私人环境文件或假表单。
- 记录了 commit 与部署版本;知道问题时怎样恢复旧版本。
常见翻车点
- **只在本机运行 dev server 就宣布上线。**把网址交给另一台设备试开;
localhost指向访问者自己的电脑。 - **输出目录选成
.next或build。**静态导出实际输出为out/;预设应选 Next.js Static HTML Export,并以构建文件确实出现为准。 - **本地 Next 版本能运行,Pages 却用过旧 Node。**检查 Pages build 日志版本,在项目根设置
.nvmrc或NODE_VERSION;确认值满足项目next版本要求后重新构建。 - **把
output: "export"当作全功能服务器。**服务器端提交、动态身份验证等需运行时的能力不会因静态导出自动存在;改成外部承接或另行规划架构。 - **根路径能开、课程详情刷新 404。**直接访问
/learn/{slug}/检验产物结构;检查 slug 是否出现在构建静态参数中、尾斜杠和部署输出是否匹配。 - **把
.env.local当作可公开资源。**核对 Git 忽略规则和out内容;若真实密钥曾推送,立即在提供方撤销并轮换,仅删除历史文件不够。 - **自定义域名报 522,就重复 build。**先确认 Pages 项目已关联该域名、DNS 名称/内容正确,再查验证状态;用
pages.dev对照定位 DNS 边界。 - **部署成功就不点 CTA。**检查公开的联系地址、表单、购买链接和隐私说明;本地测试结果不能证明线上目的地仍有效。
下一课会怎么用到今天的成果
第 10 课会把新增内容与更新页面变成有节奏的日常流程:一次变更、一次本地验证、一个 Git 记录和一次线上验收。今天记录的部署 commit 和检查清单会成为后续更新的基线。
本课技术依据
- Cloudflare Pages:静态 Next.js 站点部署指南:核对 Next.js Static HTML Export 预设、生产分支、
npx next build、out输出目录、GitHub 集成和pages.dev预览地址。 - Cloudflare Pages 构建配置:核对 Pages 如何用构建退出码判定成功,以及 Next.js 静态导出预设的构建命令和目录。
- Cloudflare Pages Build Image:核对
NODE_VERSION、.nvmrc/.node-version指定构建 Node 版本的方式。 - Cloudflare Pages Free limits:核对当前免费计划记录的构建和静态文件限制;额度可能调整,设置前应重新看官方页面。
- Cloudflare Pages Build Image:核对
NODE_VERSION、.nvmrc/.node-version指定构建 Node 版本的方式。 - Next.js Static Exports:核对
output: "export"、next build生成out/和不能依赖服务器运行时的功能边界。 - Cloudflare Pages Git Integration:核对 GitHub 仓库连接、分支发布、构建日志和首次公开 URL 的步骤。
- Cloudflare Pages Custom Domains:核对根域和子域的 DNS 前置条件、CNAME 及必须先在 Pages 中关联域名。
- Cloudflare Pages Debugging:核对构建日志定位、资源目录与 Pages/DNS 故障区分的排查方法。