我需要在 Windows 上编译 flutter 应用，因此需要在 Windows 系统上部署 Woodpecker agent 。
下面是我花了一整天的时间，探索出的方案，可以完美运行。
前置准备
[ol]
[/ol]
安装
[ol]
[/ol]
推荐开启 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 提供的具体命令。
[ol]
[/ol]
.\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
[ol]
[/ol]
参考资料（省略了官方文档）：
[ol]
[/ol]
原文链接： https://yanh.tech/2026/05/woodpecker-installation-and-usage/
版权声明：本博客所有文章除特別声明外，均为 AhFei 原创，采用 CC BY-NC-SA 4.0 许可协议。转载请注明来源 技焉洲 (yanh.tech) 。
