企业官网建设流程全解析

做前端这十几年，部署这件事的变化挺有意思。早些年接一个企业官网，流程是买台主机、开 FTP、把打包好的 dist 拖上去，改一次文案就得从头再来一遍；后来容器化流行，又开始写 Dockerfile、配 Nginx、盯着证书到期日。直到我把手上几个纯静态项目陆续迁到Cloudflare Pages上，才算真正体会到“推代码就上线”是什么感觉。Cloudflare Pages 是 Cloudflare 推出的一套面向前端项目的静态站点托管与部署平台，它把构建、全球分发、HTTPS 证书、预览环境这几件原本分散的事，收进了一条流水线：仓库连上去，填两行配置，之后每次 push 都自动出一套新环境。它不是那种“上传一个压缩包就完事”的网盘式托管，也不是要你租机器自己运维的云服务器，定位卡在中间——你只管写代码，剩下的构建机、CDN、证书、回滚全部由平台兜住。这篇东西写给三类人看：正在给公司官网或文档站找落地方案的开发，手里有博客、作品集想低成本上线的个人，以及已经用过但总觉得没摸透构建配置和 Functions 边界的同学。我会把架构链路、实操参数、踩过的坑和配额限制都摊开讲，能直接抄的部分我会给完整配置。

1. Cloudflare Pages 到底解决的是哪一类问题

1.1 从 FTP 上传到 Git 驱动部署，省掉的到底是什么

很多人第一次接触这类平台，会觉得“不就是个静态托管嘛，对象存储挂个 CDN 也能干”。这么理解没错，但漏掉了最值钱的那部分——部署流程本身被重构成了代码的一部分。传统方式里，构建发生在你自己的机器上，打包、上传、清缓存是三个手动动作，出问题只能靠人回忆“上次到底动了什么”。Git 驱动部署把这三个动作绑在了同一次提交上：哪次 commit 对应哪份产物、谁推的、什么时候生效，全都有记录，回滚就是把指针拨回去重放一次构建。

这个变化在单人项目上感知不强，一旦团队超过三个人就开始值钱了。我见过一个典型场景：市场同事要改落地页的一段文案，以前得找开发在本地改、打包、上传，来来回回半小时；现在他自己提个 PR，平台自动生成一个预览链接发到群里，谁都能点开看效果，确认了合并就上线。开发和市场的边界一下子清楚了，开发不用当人肉发布机，市场也不用排队等。

再往深一层说，它解决的是环境一致性问题。本地能构建、线上构建失败，这个经典难题以前要花大量时间对日志，而 Pages 的做法是把构建环境固定成一套镜像，Node 版本、包管理器版本都由你显式声明，剩下的差异被压缩到了最小。你不需要再去猜“线上那台机器装的是什么版本的 node-gyp”。

1.2 它和“对象存储 + CDN”方案的本质差异

对象存储加 CDN 这套组合拳，费用低、稳定，很多人第一反应是用它来托管静态站。但真用起来会发现几个绕不开的坑：索引文档要手动配（访问目录默认返回 404 而不是 index.html，得单独指定默认首页）、SPA 路由天然不支持（前端路由刷新就 404，需要靠错误页重定向兜）、缓存刷新是手工活（每次发布要主动 purge，否则用户看到旧资源）、没有预览环境（想给非技术人员看效果，只能先发到测试域名）。

Cloudflare Pages 这些都是一等公民。SPA 的 fallback 用一行_redirects规则就解决，缓存靠文件名哈希做长期缓存加 HTML 短缓存，发布即刻生效不用手动刷，每次提交自带独立预览域名。差别不在于“能不能做到”，而在于“要不要自己搭一套胶水”。胶水本身不难，难的是它常年无人维护，等到半年后有人接手时，那套脚本已经没人敢动了。

当然也要承认代价：这类平台对产物有体积和文件数量的上限，超大资源（比如几十 GB 的视频、数据集）不适合往里塞，那本来就该扔对象存储，页面里挂外链就好。静态站托管平台和对象存储不是替代关系，而是分工关系，我自己的项目就是页面走 Pages、大文件和用户上传走 R2 这类对象存储。

1.3 什么样的项目适合上，什么样的别硬上

按我这几年观察，最舒服的几类项目是这样的：文档站和博客（内容以 Markdown 为主，构建产物是纯静态）、营销落地页（更新频繁但结构固定，需要预览和 A/B 版本）、前端框架应用（React、Vue、Svelte、Astro、Next 的静态导出都行）、作品集和小工具（访问量不大但要求随时可访问、证书不出岔子）。

反过来，这几种情况我一般会劝人别硬上。第一种是服务端渲染依赖强交互的项目，如果每个页面都要实时查库拼 HTML，纯静态产物满足不了，得走 Functions 或干脆换运行环境。第二种是构建时间极长的项目，比如带大型图像处理、模型编译的站点，免费额度下每次构建都像在赌运气，得提前算好时间成本。第三种是有强合规要求、必须固定出口 IP 或部署在指定机房的业务，这类需求不在它的设计目标里。

还有一种容易被忽略的情况：项目依赖的某些原生模块在构建镜像里编不出来。这时候别急着换平台，先看是不是能换成纯 JS 实现，或者干脆把这一步挪到构建前、把产物提交进仓库。硬碰硬没意义，绕过去往往更快。

2. 一次访问背后的链路：把架构摊开看

2.1 构建产物是怎么落到边缘节点上的

理解这条链路，配置起来心里才有底。整个流程大致是四段：拉取代码 → 在隔离的构建容器里执行构建命令 → 把输出目录里的文件上传成一份不可变快照 → 这份快照被推送到全球边缘网络。注意第三步是“快照”，每次部署都是一个独立版本，不会覆盖上一次，这也是回滚能瞬间生效的原因——回滚本质上是把流量切回某个旧快照，不需要重新构建。

访问发生时，用户的请求会先到就近的边缘节点。如果这个节点上有该快照的缓存副本，直接返回；没有的话回源取一次，之后按缓存策略驻留。所以首次访问某地区可能稍慢，之后基本是本地读取。这也解释了一个常见疑惑：为什么刚发布完，有些地方立刻看到新版本，有些地方还显示旧的——通常不是没发布成功，而是浏览器或中间层缓存了 HTML。我的习惯是给 HTML 配短缓存甚至不缓存，给带哈希的静态资源配一年期强缓存，这样既保证更新及时，又保住了资源加载速度。

这里有个实操细节值得单独说：构建产物里不要出现对绝对路径的硬编码。我曾经在一个项目里把资源前缀写死成线上域名，结果预览环境的资源全从生产域名加载，看起来“能用”，实际测的根本不是当前分支的代码。用相对路径或基于环境变量注入的 base 路径，预览环境才有意义。

2.2 免费额度为什么敢给得这么大方

很多人第一次看配额表会怀疑自己看错了：静态请求和带宽基本不设限，构建次数按天或按月给一个不小的量。这套逻辑其实很朴素——静态资源的边际分发成本已经极低，而这类平台真正想卖的是配套的计算、存储和数据库产品。静态托管相当于入口，把你带进来之后，需要动态能力时自然会去用 Functions、KV、D1、R2 这些东西，后者的计费才是重头。

对我们使用者来说，这意味着两件事。第一，纯静态站的成本几乎可以忽略，哪怕流量涨十倍，账单也不会有明显变化，这点和按流量计费的 CDN 差别很大。第二，要对自己的使用方式有数。免费额度里最容易超的通常不是流量，而是构建次数和并发构建数。免费档一般只允许一个构建同时跑，团队里几个人同时推代码，后面的就得排队，遇到紧急修复会很焦虑。我一般的做法是：日常改动合并到主分支批量构建，紧急修复单独走一次直接部署，避免把构建队列堵死。

提示：配额政策会随时间调整，动手前务必去官方文档核对当前数值。别人博客里写的额度可能已经是两年前的版本，照着做容易踩空。

2.3 Pages 与 Functions 的职责边界

Pages 负责静态，Functions 负责动态，这个划分听起来简单，实际用起来最容易搞混的是什么该放进 Functions，什么该在构建期就解决掉。我的判断标准是：如果这段逻辑对每个用户返回的结果都一样，就放构建期；只有依赖请求头、Cookie、查询参数或后端状态的，才放 Functions。

举个具体例子。站点页脚的“当前年份”完全可以在构建时算好，没必要每次请求跑一遍函数；而“根据用户语言返回不同文案”就得放 Functions，因为构建期不知道访客是谁。再比如调用第三方接口拿数据展示，如果数据一天变一次，用定时构建或构建钩子就够了；如果必须实时，那才用 Functions 去代理，顺便把密钥藏在服务端，避免暴露在前端代码里。

这条边界划错，代价不小：放错方向的直接后果是请求成本和响应延迟都上去了，而收益为零。我见过一个项目把整个内容目录在函数里现读现拼，访问慢、还经常超时，其实那些内容一年也改不了几次，构建期生成成纯 HTML 就完事了。

3. 从本地项目到公网可访问：完整落地流程

3.1 动手前的本地自检清单

我踩过最亏的一次坑，是本地开发服务器跑得好好的，直接连仓库构建，结果线上白屏。事后复盘，问题出在本地 dev 模式和产线构建的路径逻辑不一样。所以现在我的习惯是，连仓库之前先在本地跑一遍真正的构建命令，用静态服务器起产物看效果，确认无误再往上推。

这份清单我基本每次都过一遍：

• 执行一次完整构建命令（不是 dev 模式），确认产物目录生成且体积正常
• 用本地静态服务器打开产物，确认首页、二级页、404 页都能访问
• 检查是否依赖了只在本地存在的文件，比如.env.local
• 确认 Node 版本需求，写进.nvmrc或配置文件，别指望线上默认版本刚好匹配
• 检查依赖锁文件已提交，避免线上按宽松版本范围装出另一套依赖树
• 确认所有文件名大小写一致，Linux 构建环境对大小写敏感，从某些系统迁过来的项目经常在这里翻车

最后一条我单独强调：大小写问题是最隐蔽的一类故障。本地不报错、构建也不报错，只有运行到具体页面时才 404，而且只在部分路由出现。定位方法是把产物目录里所有文件名列出来，和代码里的引用逐一比对，别靠肉眼扫，写个脚本更快。

3.2 连接仓库与构建参数怎么填

接入流程本身很直白：授权代码托管平台，选中仓库，填构建配置。真正需要动脑的是那几栏参数。下面是我常用的配置参考，不同框架按需替换：

关于输出目录，我要多说一句。很多框架默认输出目录和平台预设不一样，比如某些工具的产物在out或者public下，如果照着默认值填，构建日志一片绿，打开域名却是 404。遇到“构建成功但访问 404”，第一件事永远是去构建日志里找输出文件列表，看它到底往哪个目录写了东西。这个动作三十秒能定位九成问题。

还有一个细节：构建命令尽量只调一个脚本，把复杂逻辑写进package.json或单独的脚本文件里。原因很实际——平台那栏输入框对超长命令和特殊字符的处理并不总是友好，而且写在那儿的东西本地没法复现，排查时很被动。

3.3 环境变量、分支预览与生产发布

环境变量这块，我的原则是分环境分开管，别图省事一套走天下。预览环境应该指向测试用的接口和测试库，生产环境才连正式资源。如果两边共用一套变量，某天有人在预览环境里点了“清空数据”，后果你自己想。平台一般支持给生产环境和预览环境分别配置，多花两分钟，能省掉一次事故。

分支预览是这套工具里我最喜欢的功能。默认情况下，非生产分支的每次提交都会生成一个独立地址，URL 里带分支名和提交标识。用它的正确姿势是：

1. 主分支保持可发布状态，功能开发一律走分支
2. PR 描述里贴预览链接，让产品和设计直接点开验收
3. 合并前确认预览环境的数据是隔离的
4. 合并到生产分支，自动触发正式发布

这套流程跑顺之后，“你能不能先发个测试环境我看看”这类对话基本消失了。唯一要注意的是预览地址默认可能被搜索引擎收录，如果项目敏感，记得给预览环境加访问控制或者noindex头，别让半成品页面出现在搜索结果里。

发布完成之后，部署列表里会保留历史版本。真出了线上事故，回滚动作是选一个旧版本重新发布，通常几十秒内生效。我建议每次大改动前手动记一下当前生产版本的时间戳，虽然列表里看得到，但事故现场人是慌的，有个明确锚点能省不少时间。

3.4 绑定自定义域名与证书的几个细节

绑定自定义域名这一步，流程是把域名加进去、按提示配置 DNS 记录、等状态变成有效。如果域名本来就在同一家解析服务商下，通常几条记录自动带出来，几乎不用手填；跨服务商的话手动加记录，注意别和已有的冲突记录打架。

证书是自动签发和续期的，这块基本不用操心。真正容易出问题的是域名层级和重定向。比如同时绑定example.com和www.example.com，最好明确谁是主域名，另一个做 301 跳转，别让两个都能访问，否则搜索引擎会认为是重复内容。跳转用_redirects写就行，比在 DNS 层面折腾省事。

还有一个经验：先绑域名再切流量。正确顺序是把域名加进去、等证书状态正常、用一个测试路径验证解析已经指向新地址，最后再改主域名的解析。反过来做的话，中间会有一段证书没就绪、访问报错的窗口期，用户投诉就来了。我吃过一次这个亏，半夜切解析，结果证书签发排队，白白折腾一小时。

4. 进阶能力：Functions、重定向与请求头控制

4.1 Pages Functions 的目录约定与路由匹配

Functions 的用法很“文件即路由”：在项目根目录建一个约定好的函数目录，里面的文件路径直接映射成 URL 路径。比如functions/api/hello.js对应/api/hello，functions/users/[id].js里的方括号表示动态参数。这种设计上手成本低，缺点是路径和文件结构强绑定，重构时要同步挪文件。

一个最小的接口长这样：

// functions/api/hello.js export async function onRequestGet(context) { const { request, env, params } = context; const url = new URL(request.url); return new Response( JSON.stringify({ ok: true, q: url.searchParams.get('q'), ts: Date.now() }), { headers: { 'content-type': 'application/json; charset=utf-8' } } ); }

几个实操要点。第一，按方法导出（onRequestGet、onRequestPost）比统一用onRequest再自己判断方法更清晰，也少写分支。第二，中间件放在约定目录下的特定文件名里，可以对一批路由统一做鉴权、加头、日志，不用每个函数复制一遍。第三，环境变量和各类绑定通过env拿，密钥不会出现在前端代码里，这是用 Functions 代理第三方接口最大的价值。

关于路由优先级，容易踩的一个坑是静态文件和函数路径重名。比如你既有public/api/hello.json又有functions/api/hello.js，实际命中哪个要按规则判断，不是凭直觉。我的做法是干脆从源头上避免重叠，静态资源放一类前缀，接口放另一类前缀，别搅在一起。

4.2_redirects与_headers的实战写法

这两个文件要放在输出目录的根，不是源码根目录，位置错了不生效，这是新手最常见的失误。如果框架会清空输出目录，就把它们放在public这类会被原样拷贝的目录里。

_redirects的用法是这样：

# 旧路径迁移，保留权重 /old-blog/* /posts/:splat 301 # 反向代理到外部接口 /api/* https://api.example.com/:splat 200 # SPA 兜底，放最后 /* /index.html 200

三条规则对应三种典型场景。第一条是站点改版后做路径迁移，301 让搜索引擎把权重带过去，顺序很重要，具体规则要写在通配规则前面，否则会被兜底规则先吃掉。第二条是反向代理，把外部服务挂到同域下，省掉跨域配置，注意这种方式会消耗函数调用额度。第三条是单页应用的兜底，让所有未匹配路径返回首页由前端路由接管——这条必须放最后一行，放前面整个站点的静态资源都会被它拦掉。

_headers用来给响应加头，写法是按路径分组：

/* X-Frame-Options: DENY X-Content-Type-Options: nosniff Referrer-Policy: strict-origin-when-cross-origin /assets/* Cache-Control: public, max-age=31536000, immutable /*.html Cache-Control: public, max-age=0, must-revalidate

这里体现的就是前面说的缓存思路：带哈希的资源长期缓存，HTML 每次校验。安全头建议默认加上，尤其是X-Content-Type-Options和Referrer-Policy，两条加起来成本几乎为零，但能挡掉一类低级风险。内容安全策略（CSP）别一次性写死，先观察模式跑一段时间，看看有哪些内联脚本和外部资源被拦了，再逐步收紧，否则很容易把站点自己搞挂。

4.3 缓存策略与构建体积优化

缓存这块，除了响应头，还有一层是平台自身的边缘缓存。默认行为对大多数站点够用，但在“发布后必须立刻全量生效”的场景下，我会给 HTML 明确设置短缓存，避免用户看到旧页面里的旧资源引用。

体积优化上，有两个硬性约束值得记在心里：单文件大小上限和单次部署的文件数量上限。前者通常卡在几十 MB 量级，后者在两万个文件左右。正常项目很难碰到，但如果你把高清图、字体全集、视频素材一股脑塞进产物目录，很容易撞墙，而且构建时间会明显变长。

我的处理方式分三层。第一层，图片在构建期处理，转成现代格式、按展示尺寸生成多套、懒加载，单张图控制在几百 KB 以内。第二层，字体做子集化，中文字体全集动辄几 MB，按实际用到的字符裁剪能压到几十 KB。第三层，大文件外置，视频、PDF、数据集放对象存储，页面里挂链接。做完这三层，绝大多数项目能稳稳落在限制之内，构建速度也能提上来。

另一件事是构建缓存。平台一般会缓存依赖目录，让第二次构建跳过重复安装。这个机制是自动的，但会被一些写法破坏，比如每次构建都强制清缓存重装、或者没有提交锁文件导致依赖树每次都不一样。提交锁文件这件事看起来小，实际影响构建稳定性和耗时，别嫌它占仓库空间。

5. 踩坑实录：构建失败、路由 404 与配额问题

5.1 构建阶段高频故障排查表

我把这些年遇到的构建问题归了类，大部分落在下面这张表里。排查顺序建议从下往上——先看日志最后报的错，再往回找上下文。

关于最后一条，有个细节容易忽略：前端框架只有在变量名带特定前缀时才会注入到客户端代码。所以你配了变量，构建日志里也能读到，但浏览器里就是 undefined，八成是前缀不对。这个规则各框架不同，查一下文档比瞎试快。

5.2 页面能打开但资源 404 的三种典型成因

这类问题最磨人，因为首页是好的，肉眼看不出毛病。我总结下来主要三种。

第一种是绝对路径问题。项目部署在子路径下时，产物里以斜杠开头的资源引用会指到域名根，自然 404。解决办法是配置构建时的基础路径，或者全程用相对路径引用。判断方法很简单：打开开发者工具看请求的资源地址，如果少了那层子路径，就是这个问题。

第二种是大小写不一致。前面提过，这里再强调一次，因为它在本地几乎不可能复现。构建环境是区分大小写的，代码里写Header.js而文件名是header.js，本地无感，线上直接崩。我现在的做法是在构建流程里加一步检查，把所有引用路径和实际文件名做比对，早发现早修。

第三种是路由和静态文件的冲突。单页应用加了兜底规则之后，某些本该返回真实文件（比如robots.txt、sitemap.xml、站点验证文件）的请求被兜底规则截走了，返回的是 HTML，浏览器解析失败。处理办法是在兜底规则之前，给这些固定路径加显式的放行规则，或者把它们放在优先级更高的匹配位置。

5.3 配额、上限与成本控制的实操心得

免费额度对个人项目基本够用，但团队协作时几个点要提前想清楚。

构建并发是最容易卡住的地方。免费档通常只允许一个构建同时进行，几个人同时推代码就得排队。我的做法是把日常改动攒着一起合，减少构建次数；紧急修复单独走一次直接部署通道，不经过完整流水线。这不是什么高深技巧，但能把等待时间从半小时压到几分钟。

构建时长也值得盯。有些项目在本地构建五分钟，线上要十五分钟，原因是构建机性能和缓存命中率不同。如果构建时间持续增长，说明有该优化的地方——通常是依赖太多、或某一步在做重复工作。我遇到过一次，某插件每次构建都重新下载一份字典文件，后来改成构建前预取并缓存，时间直接砍掉一半。

函数调用次数是另一个容易被忽略的成本项。前面提到的反向代理方案，每一次请求都算一次函数调用，如果代理的是高频接口，量会涨得很快。静态资源走 CDN 不计这部分，但任何经过函数的请求都要算。我一般会问自己一句：这个接口真的需要实时吗？能用构建期生成的就别用函数。

注意：额度相关的具体数值随时可能调整，做容量规划时以官方当前文档为准，别拿旧数据做决策。

还有一点，部署数量也有限制。每次提交都生成一份部署，长期高频提交的项目会积累大量历史版本。一般不影响使用，但如果要做归档或审计，最好自己在外部记一份发布记录，标记清楚哪个版本对应哪次上线。

6. 横向选型：什么场景该选它，什么场景该换方案

6.1 四类部署方案的对比视角

我不太喜欢“哪个最好”这种问法，更有意义的是“在我的约束下哪个最省事”。下面这张表是我在做技术选型时会摆出来的对比维度，用类别描述，具体产品各自去对照。

从这张表能看出，静态托管平台的优势集中在流程内置：预览、回滚、证书、缓存策略都有默认答案，你少写很多胶水。代价是灵活度受限，遇到平台不支持的能力就只能绕。容器化方案的灵活度最高，但所有东西都得自己搭，包括那套最容易腐化的部署脚本。

我的实际组合通常是：前端产物走静态托管平台，大文件和用户上传走对象存储，需要服务端逻辑的部分走函数或独立服务。三者各管一段，谁也不越界。这个组合的好处是每层都能单独替换，某天要换平台，迁移成本是可控的。

6.2 迁移时的注意事项与数据可带走性

选型时有个问题值得提前问：如果哪天要迁走，成本有多大？这个问题能帮你避开很多坑。

静态托管这块，迁走的成本其实很低，因为产物就是一堆静态文件，换个地方重新部署就行。真正需要留意的是平台特有能力的绑定程度。比如你在函数里大量用了某个平台的键值存储、数据库、对象存储绑定，迁移时这部分代码得重写。我的做法是把平台特有能力包一层薄薄的适配层，业务代码只调适配层，将来换实现只改一个文件。这层抽象不用做得太重，几十行就够，但能救你一次。

域名和 DNS 这块也要提前想。如果域名解析也托管在同一家，迁移时涉及解析记录的同步切换，需要规划一个低峰时段，并且提前把新环境的证书和解析都验证好，别等到切换当天才发现某条记录没配。

还有个小细节：重定向和请求头规则是平台私有的格式，迁走时不能直接复用，得翻译成目标平台的写法。规则不多的话手动改就行，规则多的话建议在仓库里维护一份“语义化”的原始清单，各平台配置由脚本生成，避免以后再次面对一堆散落的配置。

最后分享一点个人体会。这类平台最大的价值不是省钱，也不是省机器，而是把发布这件事从“需要专门操作”变成“代码提交的自然结果”。这个转变一旦发生，团队的迭代节奏会明显不一样——小步提交变得自然，回滚不再可怕，非技术角色也能参与到验收环节里。我自己的几个项目迁过去之后，最大的变化不是访问速度，而是“改点东西发上去看看”这个动作变得毫无心理负担，而这恰恰是大部分项目能持续改进的前提。至于构建排队、产物体积这些限制，用久了自然会有感觉，提前把锁文件、输出目录、缓存策略这几件事做对，剩下的基本都是小问题。