GCDWebServer 基础使用指南

GCDWebServer 适合在 iOS 或 macOS 应用里临时提供 HTTP 服务，也能处理 WebDAV、上传和下载。下面从启动服务器到配置路由，记录一套基础用法和容易忽略的边界。

原文链接：https://xiaovv.me/2018/11/30/GCDWebServer-BasicUse/

发布日期：2018年11月30日

一、GCDWebServer 介绍

1.1 特点

• 设计优雅：仅4个核心类（server, connection, request, response）
• API 良好：注释齐全，易于定制
• 性能优秀：基于 GCD 的事件驱动模型
• 开源许可：不依赖第三方源码，遵循 BSD 许可

1.2 支持的功能

• 异步 HTTP 请求处理
• 内存优化的流处理
• 解析 HTML 表单（application/x-www-form-urlencoded 或 multipart/form-data）
• JSON 解析与序列化
• 分块传输编码、Gzip 压缩
• 本地文件服务、密码保护
• 前后台自动处理、IPv4/IPv6 支持
• 文件上传下载（GCDWebUploader）
• WebDAV 服务（GCDWebDAVServer）

1.3 不支持的功能

• 长连接
• HTTPS 请求

1.4 应用场景

• 无线 U 盘类 App
• 无线相册
• 文件导入/导出功能

1.5 GitHub 主页

https://github.com/swisspol/GCDWebServer

二、安装配置

CocoaPods 依赖

pod "GCDWebServer", "~> 3.0"
pod "GCDWebServer/WebUploader", "~> 3.0"
pod "GCDWebServer/WebDAV", "~> 3.0"

三、实现简单的 HTTP 服务器

功能

启动本地 HTTP 服务（端口 8080），返回欢迎页面。

Swift 代码示例

import UIKit
import GCDWebServer

class ViewController: UIViewController {
    override func viewDidLoad() {
        super.viewDidLoad()
        let webServer = GCDWebServer()
        webServer.addDefaultHandler(forMethod: "GET", request: GCDWebServerRequest.self) { request in
            let html = "<html><body>欢迎访问 <b>hangge.com</b></body></html>"
            return GCDWebServerDataResponse(html: html)
        }
        webServer.start(withPort: 8080, bonjourName: "GCD Web Server")
        print("服务启动成功，使用你的浏览器访问：\(webServer.serverURL!)")
    }
}

Objective-C 代码示例

#import "ViewController.h"
#import <GCDWebServer.h>
#import <GCDWebServerDataResponse.h>

@implementation ViewController
- (void)viewDidLoad {
    [super viewDidLoad];
    GCDWebServer *webServer = [[GCDWebServer alloc] init];
    [webServer addDefaultHandlerForMethod:@"GET" requestClass:[GCDWebServerRequest class] processBlock:^GCDWebServerResponse * _Nullable(__kindof GCDWebServerRequest * _Nonnull request) {
        NSString *html = @"<html><body>欢迎访问 <b>hangge.com</b></body></html>";
        return [GCDWebServerDataResponse responseWithHTML:html];
    }];
    [webServer startWithPort:8080 bonjourName:@"GCD Web Server"];
    NSLog(@"服务启动成功，使用你的浏览器访问：%@", webServer.serverURL);
}
@end

四、异步响应 HTTP 请求

功能

模拟耗时操作（如网络请求），5 秒后返回响应。

Swift 代码示例

webServer.addDefaultHandler(forMethod: "GET", request: GCDWebServerRequest.self, asyncProcessBlock: { (request, completionBlock) in
    DispatchQueue.main.asyncAfter(deadline: .now() + 5) {
        let html = "<html><body>欢迎访问 <b>hangge.com</b></body></html>"
        let response = GCDWebServerDataResponse(html: html)
        completionBlock(response)
    }
})

Objective-C 代码示例

[webServer addDefaultHandlerForMethod:@"GET" requestClass:[GCDWebServerRequest class] asyncProcessBlock:^(__kindof GCDWebServerRequest * _Nonnull request, GCDWebServerCompletionBlock _Nonnull completionBlock) {
    dispatch_after(dispatch_time(DISPATCH_TIME_NOW, (int64_t)(5 * NSEC_PER_SEC)), dispatch_get_main_queue(), ^{
        NSString *html = @"<html><body>欢迎访问 <b>xiaovv.me</b></body></html>";
        GCDWebServerDataResponse *reponse = [GCDWebServerDataResponse responseWithHTML:html];
        completionBlock(reponse);
    });
}];

五、HTTP 请求重定向

功能

将根路径 / 重定向至 /index.html。

Swift 代码示例

webServer.addHandler(forMethod: "GET", path: "/", request: GCDWebServerRequest.self) { request in
    let url = URL(string: "index.html", relativeTo: request.url)
    return GCDWebServerResponse(redirect: url!, permanent: false)
}

Objective-C 代码示例

[webServer addHandlerForMethod:@"GET" path:@"/" requestClass:[GCDWebServerRequest class] processBlock:^GCDWebServerResponse * _Nullable(__kindof GCDWebServerRequest * _Nonnull request) {
    NSURL *url = [NSURL URLWithString:@"index.html" relativeToURL:request.URL];
    return [GCDWebServerResponse responseWithRedirect:url permanent:NO];
}];

六、实现 FORM 表单功能

功能

GET 请求返回表单页面，POST 请求处理提交数据。

Swift 代码示例

// GET 请求返回表单
webServer.addHandler(forMethod: "GET", path: "/", request: GCDWebServerRequest.self) { request in
    let html = """
    <html><body>
    <form name="input" action="/" method="post" enctype="application/x-www-form-urlencoded">
        用户名: <input type="text" name="username">
        <input type="submit" value="提交">
    </form>
    </body></html>
    """
    return GCDWebServerDataResponse(html: html)
}

// POST 请求处理表单数据
webServer.addHandler(forMethod: "POST", path: "/", request: GCDWebServerURLEncodedFormRequest.self) { request in
    let formRequest = request as! GCDWebServerURLEncodedFormRequest
    let value = formRequest.arguments["username"] ?? ""
    let html = "<html><body>\(value)</body></html>"
    return GCDWebServerDataResponse(html: html)
}

Objective-C 代码示例

// GET 请求返回表单
[webServer addHandlerForMethod:@"GET" path:@"/" requestClass:[GCDWebServerRequest class] processBlock:^GCDWebServerResponse * _Nullable(__kindof GCDWebServerRequest * _Nonnull request) {
    NSString *html = @"<html><body><form name=\"input\" action=\"/\" method=\"post\" enctype=\"application/x-www-form-urlencoded\">用户名: <input type=\"text\" name=\"username\"><input type=\"submit\" value=\"提交\"></form></body></html>";
    return [GCDWebServerDataResponse responseWithHTML:html];
}];

// POST 请求处理表单数据
[webServer addHandlerForMethod:@"POST" path:@"/" requestClass:[GCDWebServerURLEncodedFormRequest class] processBlock:^GCDWebServerResponse * _Nullable(__kindof GCDWebServerRequest * _Nonnull request) {
    GCDWebServerURLEncodedFormRequest *formRequest = (GCDWebServerURLEncodedFormRequest *)request;
    NSString *value = [formRequest.arguments objectForKey:@"username"];
    NSString *html = [NSString stringWithFormat:@"<html><body>%@</body></html>", value];
    return [GCDWebServerDataResponse responseWithHTML:html];
}];

七、实现静态文件目录网站

功能

将整个 Home 目录作为静态网站根目录，支持文件浏览和下载。

Swift 代码示例

webServer.addGETHandler(forBasePath: "/", directoryPath: NSHomeDirectory(), indexFilename: nil, cacheAge: 3600, allowRangeRequests: true)

Objective-C 代码示例

[webServer addGETHandlerForBasePath:@"/" directoryPath:NSHomeDirectory() indexFilename:nil cacheAge:3600 allowRangeRequests:YES];

效果

访问 http://localhost:8080 显示沙盒目录结构，可浏览和下载文件。

八、实现动态网站

功能

结合静态资源（CSS/JS/图片）和动态 HTML 模板，实现交互式网站。

项目结构

Website/
  ├── index.html
  ├── default.css
  ├── jquery.js
  └── imgs/
      ├── 1.png
      ├── 2.png
      ├── 3.png
      └── 4.png

HTML 模板（index.html）

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>hangge.com</title>
  <link rel="stylesheet" href="default.css" type="text/css">
  <script src="jquery.js" charset="utf-8"></script>
  <script>
     $(document).ready(function(){
       $("li").click(function(){
         var data = $(this).attr("data");
         $("#image1").attr("src","imgs/"+data);
       });
     });
  </script>
</head>
<body>
   <div class="left">
     <div class="title">%var_title%</div>
     <ul>%var_li%</ul>
   </div>
   <img id="image1" src="imgs/1.png">
</body>
</html>

Swift 代码示例

let websitePath = Bundle.main.path(forResource: "Website", ofType: nil)
webServer.addGETHandler(forBasePath: "/", directoryPath: websitePath!, indexFilename: nil, cacheAge: 3600, allowRangeRequests: true)

webServer.addHandler(forMethod: "GET", pathRegex: "^/.*\\.html$", request: GCDWebServerRequest.self) { request in
    let var_li = "<li data='1.png'>图片1</li><li data='2.png'>图片2</li><li data='3.png'>图片3</li><li data='4.png'>图片4</li>"
    let variables = ["var_title": "点击切换图片", "var_li": var_li]
    let htmlTemplate = websitePath! + request.path
    return GCDWebServerDataResponse(htmlTemplate: htmlTemplate, variables: variables)
}

Objective-C 代码示例

NSString *websitePath = [[NSBundle mainBundle] pathForResource:@"Website" ofType:nil];
[webServer addGETHandlerForBasePath:@"/" directoryPath:websitePath indexFilename:nil cacheAge:3600 allowRangeRequests:YES];

[webServer addHandlerForMethod:@"GET" pathRegex:@"^/.*\\.html$" requestClass:[GCDWebServerRequest class] processBlock:^GCDWebServerResponse * _Nullable(__kindof GCDWebServerRequest * _Nonnull request) {
    NSString *var_li = @"<li data='1.png'>图片1</li><li data='2.png'>图片2</li><li data='3.png'>图片3</li><li data='4.png'>图片4</li>";
    NSDictionary *variables = @{@"var_title": @"点击切换图片", @"var_li": var_li};
    NSString *htmlTemplate = [websitePath stringByAppendingString:request.path];
    return [GCDWebServerDataResponse responseWithHTMLTemplate:htmlTemplate variables:variables];
}];

效果

访问 http://localhost:8080 显示动态页面，点击左侧列表切换右侧图片。

九、实现文件上传下载服务

功能

通过 GCDWebUploader 提供 Web 界面的文件管理功能。

Swift 代码示例

let documentsPath = NSHomeDirectory() + "/Documents"
let webUploader = GCDWebUploader(uploadDirectory: documentsPath)
webUploader.start(withPort: 8080, bonjourName: "Web Based Uploads")

Objective-C 代码示例

NSString *documentsPath = [NSHomeDirectory() stringByAppendingPathComponent:@"Documents"];
GCDWebUploader *webUploader = [[GCDWebUploader alloc] initWithUploadDirectory:documentsPath];
[webUploader startWithPort:8080 bonjourName:@"Web Based Uploads"];

效果

访问 http://localhost:8080 显示文件管理界面，支持上传、下载、删除、重命名等操作。

十、实现 WebDAV 服务器

功能

通过 GCDWebDAVServer 提供 WebDAV 协议支持，允许专业客户端访问。

Swift 代码示例

let documentsPath = NSHomeDirectory() + "/Documents"
let webDAVServer = GCDWebDAVServer(uploadDirectory: documentsPath)
webDAVServer.start(withPort: 8080, bonjourName: "WebDAV Server")

Objective-C 代码示例

NSString *documentsPath = [NSHomeDirectory() stringByAppendingPathComponent:@"Documents"];
GCDWebDAVServer *webDAVServer = [[GCDWebDAVServer alloc] initWithUploadDirectory:documentsPath];
[webDAVServer startWithPort:8080 bonjourName:@"WebDAV Server"];

效果

使用 Transmit、Cyberduck 等 WebDAV 客户端连接 http://localhost:8080 管理文件。

总结

GCDWebServer 是一个功能强大、易于使用的 iOS Web 服务器库，适用于以下场景：

1. 无线文件传输：实现无线 U 盘、无线相册等功能
2. 嵌入式 Web 服务：在 App 中集成轻量级 Web 服务
3. 数据导入导出：通过浏览器或专业客户端管理文件
4. 快速原型开发：快速搭建内部测试用的 Web 服务

所有代码示例均包含 Swift 和 Objective-C 两个版本，方便不同语言背景的开发者使用。

文档生成时间：2026-02-27