我需要在 Windows 上编译 flutter 应用，因此需要在 Windows 系统上部署 Woodpecker agent 。

下面是我花了一整天的时间，探索出的方案，可以完美运行。

前置准备

1. 在 Windows 上安装 git
2. 把这个路径加入环境变量里系统的 PATH C:\Program Files\Git\usr\bin，这里面提供了 cat 等工具
3. 在 Woodpecker 网页上注册一个 agent token ，参考 https://woodpecker-ci.org/docs/administration/configuration/agent#using-agent-token
4. 建议安装 curl ，下载网址 https://curl.se/windows/ ，下载后就是一个可执行文件，将之放到任意文件夹，然后将其所在目录添加到环境变量里
5. 建议安装 Woodpecker 的 git 插件 https://woodpecker-ci.org/plugins/git-clone ，clone 仓库需要它，也是一个单纯的可执行文件，下载后，推荐放到 C:\woodpecker_plugin ，然后把这个路径添加到环境变量里

安装

1. 创建 C:\tmp 作为工作目录。因为 Windows 对路径名称有长度限制，而 agent 默认的工作目录路径很长，对于 flutter 项目，很容易触发长度限制导致编译失败
2. 在 https://github.com/woodpecker-ci/woodpecker/releases 里下载对应的 agent ，需要和服务端的版本号一样

推荐开启 Windows 长路径支持。通过 win + R 打开”运行“，然后输入 gpedit.msc 确定，按路径寻找：计算机配置 → 管理模板 → 系统 → 文件系统 → 启用 Win32 长路径，右键编辑，设置为：已启用。

运行

务必在 PowerShell 里运行

先配置环境变量，需要填入 WOODPECKER_SERVER 和 WOODPECKER_AGENT_SECRET 。

$env:WOODPECKER_SERVER="1.2.3.4:9000"
$env:WOODPECKER_AGENT_SECRET="LK34BX5XDXNHADFBFGFAM5ENGM44FBSZBDNGFZSVDCDWOGA===="
$env:WOODPECKER_MAX_WORKFLOWS="1"
$env:WOODPECKER_BACKEND="local"
$env:WOODPECKER_PLATFORM="windows/amd64"
$env:WOODPECKER_BACKEND_LOCAL_TEMP_DIR="C:\tmp"

由于 Windows 本身不支持 docker ，这里是在本机上执行的，为了避免多个工作者干扰，最好把 WOODPECKER_MAX_WORKFLOWS 设置为 1

运行

.\woodpecker-agent.exe

测试是否能正常运行

可以在一个实验的仓库，使用下面的配置进行测试。如果正常运行，会打开 C:\Users\ 文件夹。

when:
  - event: push
    branch: main

labels:
  platform: windows/amd64
  backend: local

steps:
  - name: test-exprorer
    image: powershell
    commands:
      - explorer C:\Users\

到这里就结束了，需要注意的是，commands 里必须用 powershell 的命令。

使用 ssh 克隆仓库

我猜测 git plugin 是通过 Git Credential Manager 进行校验，这样经常失败 remote: Failed to authenticate user，更可靠的方案是直接用用户名和密码登录，但是这个 plugin 不支持，另外这样也不安全。

要使用 ssh 校验，同样稳定，不过步骤稍微繁琐。

首先，需要在 Gitea 添加公钥，流程可看 https://yanh.tech/2025/04/deployment-process-of-gitea/#ssh 。

然后，替换默认的 clone 步骤，如下：

clone:
  git:
    image: woodpeckerci/plugin-git
    settings:
      use-ssh: true
      remote-ssh: ssh://[email protected]:2222/vfly2/plantodo.git
      ssh-key: C:/Users/Administrator/.ssh/id_ed25519

这样之后，就不会再发生 Failed to authenticate user

Windows Service

但是，我想实现开机自启、失败自动重启，有办法吗？

使用 Windows Service 。查看 以 Windows 服务运行程序并开机自启 - 技焉洲 了解步骤，下面是针对 woodpecker 提供的具体命令。

1. 确保原程序在命令行下能正常启动。
2. 到 https://github.com/mtkennerly/shawl/releases 下载压缩包，解压后有一个 shawl。
3. 以管理员权限打开 powershell ，使用 shawl 添加服务，在原命令前加点内容就行，以及使用绝对路径：

.\shawl.exe add --name woodpecker_agent `
  --env WOODPECKER_SERVER="1.2.3.4:9000" `
  --env WOODPECKER_AGENT_SECRET="LK34BX5XDXNHADFBFGFAM5ENGM44FBSZBDNGFZSVDCDWOGA====" `
  --env WOODPECKER_MAX_WORKFLOWS="1" `
  --env WOODPECKER_BACKEND="local" `
  --env WOODPECKER_PLATFORM="windows/amd64" `
  --env WOODPECKER_BACKEND_LOCAL_TEMP_DIR="C:\tmp" `
  -- C:/Users/Administrator/Downloads/woodpecker-agent/woodpecker-agent.exe

1. 打开命令行，注意不是 powershell ，sc 命令只能在命令行里运行才能看到结果，不明白原因
2. 查看服务是否添加成功： sc qc woodpecker_agent
3. 指定运行服务的用户： sc config woodpecker_agent obj=".\Administrator" password="456"。（必做，因为默认的运行用户是 local system ，这和我们直接在 PowerShell 启动的用户不一样，可能会有奇奇怪怪的错误）
4. 先试一下启动服务： sc start woodpecker_agent
5. 设置开机自启： sc config woodpecker_agent start=auto

参考资料（省略了官方文档）：

1. https://github.com/GECO-IT/woodpecker-windows/blob/main/agent/backend-local/README.md

原文链接： https://yanh.tech/2026/05/woodpecker-installation-and-usage/

版权声明：本博客所有文章除特別声明外，均为 AhFei 原创，采用 CC BY-NC-SA 4.0 许可协议。转载请注明来源 技焉洲 (yanh.tech) 。