Vapor 教程2026-08-05 · 约 9 分钟

环境搭建与第一个 Vapor 项目

用 Vapor 写后端，第一步是把工具链装好，然后点一下运行、在浏览器里看到那句经典的 “It works!”。这一篇带你从零把环境跑通，并认识一个 Vapor 工程里都有哪些文件。

一、先搞清你手上有什么

Vapor 是纯 Swift 写的框架，所以前提是你得有一份能用的 Swift 工具链。Swift 的工具链分两种来源：

macOS：直接装 Xcode（App Store 里搜索安装），它自带 Swift 编译器；再在终端执行一次 xcode-select --install 装好命令行工具即可。
Ubuntu / Linux：去 Swift 官网按指引下载对应版本的工具链，或者用下文的 Vapor 工具箱源码方式。

版本对应关系：Vapor 4 需要 Swift 5.2 以上。装之前先跑一句 swift --version，确认 Swift 已经就位、且版本够新，能省掉后面一堆诡异报错。

工具箱（Toolbox）不是框架本身，而是一个脚手架：帮你新建工程、跑测试、生成 Xcode 工程。装好它会方便很多。

brew install vapor

装完后验证一下：

vapor --version

Linux 上没有对 Swift 支持特别完善的 IDE，可以从源码编译工具箱：

git clone https://github.com/vapor/toolbox.git
cd toolbox
git checkout <desired version>
make install

日常开发可以在 VS Code 里装 sswg.swift-lang 插件，或者直接用 Vim。完成这步，开发环境就基本齐了。

用工具箱一键生成模板工程：

vapor new HelloVapor

过程中它会问你要不要顺手加入 Leaf（模板）和 Fluent（数据库）等依赖，新手可以先一路回车用默认配置，后面需要再补。

进入目录并打开：

cd HelloVapor
vapor xcode

这条命令会生成 Xcode 工程并自动打开。运行方式有两种：

项目启动后默认监听 localhost:8080。打开浏览器访问它，你就能看到第一句问候。

小技巧：在 macOS 上，进入 Vapor 项目根目录运行 vapor xcode（或 open Package.swift），即可用 Xcode 打开整个工程，开发、运行、调试一条龙。Linux 上则靠 swift build 与 vapor run 编译运行。

模板工程看起来文件不少，但核心就那么几个：

路径	作用
`Package.swift`	依赖清单，所有第三方库（Vapor、Leaf、Fluent…）都在这里声明
`Sources/App/configure.swift`	配置服务：数据库连接、模板引擎、中间件都在这里注册
`Sources/App/routes.swift`	路由表，建立「网址 → 处理函数」的对应关系（核心文件）
`Sources/App/boot.swift`	启动时执行的钩子（Vapor 3 结构；Vapor 4 合并进了 `main.swift`）
`Public/`	静态文件（图片、CSS、JS）直接对外提供
`Resources/Views/`	Leaf 模板文件存放处（做网页时才用）

真正决定「用户访问某个网址时返回什么」的，就是 routes.swift。下一篇我们会专门拆它。

打开 Sources/App/routes.swift，默认内容里通常已经有一句：

import Vapor

func routes(_ app: Application) throws {
    app.get { req in
        return "It works!"
    }
}

保持原样，运行项目，浏览器访问 http://localhost:8080，页面上出现 It works! 就说明环境彻底通了。这就是你的第一个 Vapor 接口——它把一个 URL（/）映射到了一段返回字符串的代码。

环境跑通只是起点。下一篇我们聊聊路由：怎么定义不同的网址、怎么接收前端发来的数据、又怎么返回 JSON 给调用方。