如何使用 Surge 部署静态网站?

更新时间 2026-10-02

在项目目录中运行 surge 命令，按提示确认项目路径和域名，即可把静态站点发布到 Surge 的 CDN 上。它面向静态网站和客户端应用，通过 CLI 完成部署，适合手写 HTML/CSS/JS、静态站点生成器产物或前端构建结果。前提是你已经有一个可本地打开或构建完成的静态项目，并且本机可以运行 npm 相关命令。

部署前需要准备什么

Surge 的定位是“Static web publishing for Front-End Developers”，部署入口是命令行。开始前确认：

项目已经生成静态文件，例如 index.html、CSS、JS 和资源文件。
本机可以使用 Node.js 与 npm 环境（Surge CLI 通过 npm 安装或作为 devDependency 使用）。
你清楚要发布的目录，例如 dist、build 或项目根目录。
如果使用自定义域名，需要能修改该域名的 DNS 解析。

Surge 页面列出了这些随项目提供的特性：免费自定义域名支持、为 surge.sh 子域名提供免费 SSL、单页应用的 pushState 支持、自定义 404.html、通过 CLI 无障碍部署、跨域资源共享支持等。这些是选择 Surge 时可以直接核对的部署能力。

用 CLI 发布：从安装到上线

Surge 官方给出的最短路径是“六次击键”：在项目目录中输入 surge 并回车，项目就会立即上线。实际流程可以拆成下面几步。

1. 安装 Surge CLI

如果只是本地使用，可以全局安装；如果希望把部署写进项目脚本，可以安装为开发依赖：

npm install --save-dev surge

页面同时提到 Grunt、Gulp、npm run scripts 等集成方式，说明 Surge 可以嵌入你已有的构建工具链，而不是要求换一套发布流程。

2. 在项目目录运行部署命令

进入项目目录后执行：

surge

预期会看到类似下面的交互过程：

$ surge
    project: path/to/my-project
    domain: my-project.surge.sh
    upload: [ ============ ]
    Success! Published and running at my-project.surge.sh

这里需要理解三个输入的含义：

project：要上传的本地目录。默认通常是当前目录，也可以手动指定路径。
domain：发布后使用的域名。首次部署可以接受 Surge 生成的 *.surge.sh 子域名，也可以填写自定义域名。
upload：上传进度。出现 Success! 和可访问地址，表示发布完成。

3. 验证部署结果

部署成功后，终端会输出类似 Published and running at my-project.surge.sh 的地址。用浏览器打开该地址，确认首页、静态资源和子页面能正常加载。如果项目是单页应用，还要检查直接访问非根路径时是否按预期回退到入口页面。

4. 指定项目路径和域名

如果不想使用默认值，可以在命令中直接指定，减少交互：

surge path/to/my-project my-project.surge.sh

第一个参数是本地目录，第二个参数是目标域名。这样适合把部署命令固定到 npm script 或 CI 流程中。

和构建工具、静态站点生成器怎么配合

Surge 的设计是“augments the tools you already love”，也就是增强现有工具，而不是替代它们。页面给出的集成方式包括：

方式	做法	适用场景
npm run scripts	安装 Surge CLI 后，在 `package.json` 中配置脚本	已有 npm 工作流的前端项目
Grunt	安装 `grunt-surge` 插件，使用 `grunt deploy`	使用 Grunt 构建的项目
Gulp	把 surge 作为 devDependency，在 Gulpfile 中调用	使用 Gulp 构建的项目
Git Hooks	每次推送到 GitHub 时部署，不需要切换分支	希望推送即发布的仓库
Jekyll	本地编译后发布到 Surge	Jekyll 站点，避免分支和插件限制
静态站点生成器	用 Surge CLI 发布生成结果	手写 HTML 或高度定制的生成器

关键点是：先让构建工具产出静态文件，再把产物目录交给 Surge。不要把源文件目录和构建产物目录混在一起，否则可能把不需要的文件一起上传。

常见卡点

部署后页面 404 或资源加载失败：先确认上传的是构建产物目录，而不是项目根目录；再检查资源路径是否以 / 开头导致子路径下解析错误。
单页应用刷新后 404：Surge 提供 pushState 支持，但需要确认入口文件和路由回退配置正确。
自定义域名不生效：Surge 支持免费自定义域名，但域名解析需要按 Surge 的要求配置；DNS 生效需要时间。
想用自定义 404 页面：在项目中放置 404.html，Surge 会使用它作为错误页。
团队协作：页面提到 “Invite your team”，说明可以通过邀请成员参与项目，而不是只靠个人账号发布。

什么时候选 Surge

如果你的项目是纯静态站点或客户端应用，并且希望用命令行快速发布、把部署接入现有构建工具，Surge 的路径很短：安装 CLI、运行 surge、确认域名、拿到可访问地址。它提供 surge.sh 子域名、免费 SSL、自定义域名支持和 pushState 等静态发布常用能力。

如果你需要服务端渲染、数据库或复杂后端逻辑，Surge 的静态发布模型并不覆盖这些需求。先确认项目能产出静态文件，再决定是否用它作为发布层。