如果你问我在 Windows 下把 Touch™ 这套开发环境完整跑起来有多麻烦我的回答是装完那一刻你会觉得不过如此但中间任何一个版本错位、PATH 写错、容器起不来都能让你耗掉整个下午。这篇东西就是把我自己从零到一搭建 Touch™ Windows 开发环境的整个过程、选型理由、踩坑记录全部摊开讲。先说清楚本文里的 Touch™ 是什么它不是 Linux 里的touch命令也不是柯达扫描仪那个 Smart Touch 软件而是目前项目里使用的这套触摸交互开发平台覆盖两块——上位机端的触控界面与应用框架以及 STM32、RP2040 这类 MCU 设备端的触摸驱动与固件 SDK。也就是说要在 Windows 上把 Touch™ 玩转你既得配好常规的桌面开发环境终端、Git、语言运行时、容器也得把嵌入式交叉编译链一起理顺。这篇文章适合谁刚拿到 Touch™ SDK、看着 README 不知道从哪下手的初学者以及被环境问题反复折磨、想一次性搞清楚每层依赖关系的老手。我会按实际搭建顺序写也会在每个关键位置解释“为什么必须这么做”。1. Touch™ 环境选型的底层逻辑不是全家桶是分层依赖1.1 从 SDK 依赖反推环境总览刚开始我也以为装个 IDE 就完事直到 Touch™ 的安装脚本跑了一半报curl: command not found后来编译设备端固件又缺 ARM 工具链才意识到这套环境要拆成好几层。下面是我最终确定的环境清单层次组件版本建议用途宿主系统Windows 10 22H2 或 Windows 1164 位主力开发机终端层Windows Terminal PowerShell 7最新稳定版统一命令入口包管理winget scooplatest软件安装与版本管理代码管理Git for Windows2.47拉取 Touch™ SDK 与子模块Java 运行时Temurin JDK17 LTSTouch™ 后端与构建脚本Python 环境Miniconda Python 3.113.11/3.12自动化脚本、烧录与测试辅助前端构建Node.js 20 LTS nvm-windows20.x上位机界面构建容器层Docker Desktop WSL24.x运行 Redis、Elasticsearch嵌入式工具链ARM GCC CMake EIDEgcc-arm-none-eabi 10.3MCU 固件编译芯片支持包STM32CubeMX / RP2040 SDK6.x / 2.x工程生成分清楚“必须”和“可选”很重要。Touch™ 上位机如果只跑桌面端Node.js 和 Java 一般躲不开如果设备端用 STM32那 ARM GCC 和 STM32CubeMX 就是刚性需求。Redis 和 Elasticsearch 看项目阶段前期调试可以先用容器按需起没必要全装到 Windows 服务里。1.2 为什么最终选了 Windows 而不是切到 Linux我自己是长期 Windows 用户也试过在 Ubuntu 里搭 Touch™最后又回到 Windows原因非常实际Touch™ 的设备端工具链里Keil MDK 和 IAR 只有 Windows 版本很多烧录器驱动只提供 Windows 版连 ARM GCC 在 Windows 下的路径习惯都被团队验证过。Linux 的优势保留在 WSL2 里既能在 Windows 上写代码又能用 Ubuntu 的包管理器和 cmake 生态还不耽误原生跑 Windows 专用软件。强调一个我踩过的坑安装路径不要带中文、不要带空格。Touch™ 的编译脚本里如果你用D:\开发环境\Touch SDK这种路径大概率会在某个深层子模块的构建脚本里炸掉报错信息还特别隐晦。我现在的习惯是统一放D:\dev\坏处是目录看起来不性感好处是几乎所有工具链都认识它。2. 先把 Windows 这台“母机”收拾利落终端、包管理与 Git2.1 Windows Terminal PowerShell 7让命令行先正常起来很多人忽略终端层直接双击安装包乱装结果 later 跑 SDK 脚本时报权限、报乱码、报闪退一半都是终端环境的问题。我第一步就用 winget 装好基础套装命令如下winget install Microsoft.WindowsTerminal winget install Microsoft.PowerShell winget install Git.Git装完第一件事打开 Windows Terminal 的设置把默认配置文件改成 PowerShell 7。这一步能避免大量由 Windows PowerShell 5.1 版本差异导致的问题Touch™ 自带的一些脚本在新版里跑得明显更顺。接着处理执行策略。很多时候你运行.ps1脚本系统直接给出“无法加载文件因为在此系统上禁止运行脚本”这其实是安全策略不是程序坏了。执行下面命令只在当前用户生效不升高系统整体权限Set-ExecutionPolicy -Scope CurrentUser RemoteSigned解释一下RemoteSigned的含义本地创建的脚本可以运行从网络下载的脚本必须带有效签名。这个策略比较平衡既不影响日常脚本又保留安全边界。如果你某些脚本是从公司内网拉下来的用Unblock-File xxx.ps1解除锁定即可。2.2 脚本双击闪退和 PATH 不生效先按顺序排查“Windows 脚本命令闪退”是个搜索热词我刚开始也遇到双击一个.bat窗口闪一下就消失啥都看不出来。后来总结了一套固定排查顺序每个环境问题都能对上不要双击把脚本拖进 PowerShell 或 Windows Terminal 里执行让报错停留。看执行策略再看脚本文件是否被 Mark of the Web 锁定右键属性里是否有“解除锁定”按钮。检查脚本第一行是否有echo off和pause如果没有失败后窗口直接关闭很正常。如果报错信息里出现“不是内部或外部命令”说明脚本依赖的某个程序不在 PATH 里。PATH 不生效的情况特别坑我测试过一台新机器装了 JDK 却始终java -version报错原因是在环境变量窗口里改完没有开新终端旧窗口里 PATH 还是启动时的快照。另外系统环境变量和用户环境变量同时存在时系统变量排在前面如果你两个地方都配了 JAVA_HOME以先出现的那个为准经常被这个坑到。2.3 Git 与 SSHTouch™ SDK 的拉取通道Touch™ 的 SDK 基本都是 Git 仓库而且用了不少 submodule比如设备端依赖的 FreeRTOS 内核、TCP/IP 协议栈。拉取时别省事git clone --recursive https://github.com/touch-sdk/touch-sdk.git如果子模块已经初始化到一半失败可以用git submodule update --init --recursive补拉。这里提醒一点Windows 下 Git 安装时默认会配core.autocrlftrue把 LF 换成 CRLF对于 C/C 和 Python 项目基本没问题但在 shell 脚本和 Makefile 上偶尔会出诡异错误。我个人的做法是全局关掉自动转换只对特定仓库单独开git config --global core.autocrlf falseSSH 配置也建议一开始就做好。Touch™ 内部有些私有子仓库走 SSH 协议生成密钥后把公钥配好免得后面被权限问题卡住ssh-keygen -t ed25519 -C your_emailexample.com3. 语言运行时JDK、Python、Node.js 的共存装配方案3.1 JDK 17 LTS手动配 JAVA_HOME 的原因与方法Touch™ 的后端构建脚本基于 Gradle而 Gradle 对 JDK 版本比较敏感太新了可能触发兼容警告太旧了直接不支持。我选 Temurin 17 LTS它兼容性上比较安全维护周期也长。装完 MSI 后别急着关安装向导它会提示配置 JAVA_HOME建议选上省得手动再写一遍。手动配置的标准化流程新建系统环境变量JAVA_HOME值填 JDK 的实际安装路径比如C:\Program Files\Eclipse Adoptium\jdk-17.0.12.7-hotspot。在Path里新增%JAVA_HOME%\bin。新开一个终端执行java -version验证。这里特别说一下“为什么不是直接用安装包帮你配好的 PATH而是要多此一举设 JAVA_HOME”。因为后续很多构建工具并不直接看 PATH 里的 java而是去查 JAVA_HOME 变量。Gradle、Tomcat、Elasticsearch 这类 Java 生态工具全都依赖 JAVA_HOME所以必须显式设置。如果你机器上已经装了 Oracle JDK 或别的 JDK强烈建议把所有 Java 相关旧变量清掉再重新配否则java -version输出版本和实际 PATH 里的不一致排查起来非常崩溃。3.2 Python、Miniconda 与 VSCode 解释器别让脚本环境裸奔Windows 下 Python 最大的坑是版本管理混乱。我见过有人在官网下载 Python 一路点下一步最后python指向系统应用商店的假 Python或者pip装到了某个凭空的路径。用 Python 自带的pylauncher 可以先查看机器上已有的版本py -0但我不建议直接用系统 Python 跑 Touch™ 的项目脚本因为项目管理依赖、版本升级时很容易把基础环境搅浑。推荐用 Miniconda。很多教程推荐 Anaconda但 Anaconda 对开发机来说过于臃肿Miniconda 足够。Miniconda 安装有个关键选项是否把 conda 加入 PATH。我的建议是安装时勾选加入 PATH省去后面手动配 conda 位置的麻烦。装完后为 Touch™ 单独建一个虚拟环境conda create -n touch python3.11 -y conda activate touch pip install -r requirements-dev.txtVSCode 里也要跟着切解释器CtrlShiftP打开命令面板输入Python: Select Interpreter选到touch环境。这一步如果漏了你会发现终端里明明是 conda 环境VSCode 的调试器却用着系统 Python装了一堆依赖照样报 ModuleNotFoundError。3.3 Node.js 与 nvm-windows前端构建依赖的真实管理方式Touch™ 上位机界面我这边用的是 Electron Vite 那套所以 Node.js 躲不掉。Windows 上直接装官网 Node 确实简单但一旦项目要求切换 Node 版本就痛苦了。干脆一开始就装 nvm-windows用它管理 Nodewinget install CoreyButler.NVMforWindows nvm install 20.17.0 nvm use 20.17.0安装完 nvm 后原来的系统 Node 路径会被接管如果nvm list看不到已安装版本检查 nvm 的settings.txt里 root 路径是否正确。npm 官方源在国内访问速度不稳定可以配置 npmmirror 镜像来提速这个属于常规技术操作不影响安全与合规npm config set registry https://registry.npmmirror.com装完 Node、切好版本后跑一下npm install如果项目里有node-gyp相关的原生依赖Windows 下还必须确保安装了 Build Tools 或者 Visual Studio Build Tools否则编译阶段必然报MSB4132之类的错误。4. 用 Docker Desktop WSL2 把中间件变成“即用即弃”的容器4.1 WSL2 才是 Docker 在 Windows 上顺畅运行的前提很多教程直接让你装 Docker Desktop但对 WSL2 一笔带过。实际体验下来Docker on Windows 能不能平稳跑八成的锅在 WSL2 上。WSL2 不是虚拟机它是一个轻量级实用工具集和宿主机共享内核性能比 VM 方案好太多。安装顺序wsl --install -d Ubuntu-22.04 wsl --set-default-version 2如果机器上有老版本的 WSL1注意wsl -l -v查看版本确定是 2。另外可以在用户目录下建一个.wslconfig限制 WSL2 的内存占用别让它把开发机内存吃光[wsl2] memory6GB processors4 swap2GB改完执行wsl --shutdown再重进。这一步在只有 16GB 内存的笔记本上尤其重要Docker 加 WSL2 加 Electron 加 VSCode 同时躺着内存不够会很卡。4.2 Docker Desktop 安装与 Redis、Elasticsearch 的容器化启动安装 Docker Desktop 用 winget 一行搞定winget install Docker.DockerDesktop装完后打开 Settings确保 Use the WSL 2 based engine 是勾选状态。如果 Docker Desktop 一直起不来检查 BIOS 里虚拟化是否开启systeminfo输出里能看到 Hyper-V 要求是否满足。中间件的启动我建议写成一个docker-compose.yml放在 Touch™ 项目根目录维护起来清爽services: redis: image: redis:7-alpine ports: - 6379:6379 volumes: - redis-data:/data elasticsearch: image: docker.elastic.co/elasticsearch/elasticsearch:8.14.0 environment: - discovery.typesingle-node - xpack.security.enabledfalse ports: - 9200:9200 volumes: - es-data:/usr/share/elasticsearch/data volumes: redis-data: es-data:执行docker compose up -d即可。注意 Elasticsearch 8.x 默认开了安全认证如果只是本地开发用xpack.security.enabledfalse关掉不然启动后访问 9200 会碰到 401。另一个常被忽略的问题是 Elasticsearch 容器在 WSL2 里启动时报max virtual memory areas vm.max_map_count [65530] is too low。这个错误跟“Windows 启动 Elasticsearch”搜索热词高度重合解决方法是在 WSL2 终端里执行sudo sysctl -w vm.max_map_count262144要永久生效在/etc/sysctl.conf里加一行vm.max_map_count262144然后sudo sysctl -p重载。4.3 为什么不在 Windows 上直接装 Redis / Elasticsearch搜索热词里“redis windows 下载”“windows版本redis下载”都很高频但我要泼盆冷水Redis 官方从未提供 Windows 原生支持网上那些 Windows 版本多为社区移植版本滞后当开发环境问题排查到协议栈时容易和真实环境行为不一致。Elasticsearch 虽然有 Windows zip 包但解压后要配path.data、要在服务里自启、升级还麻烦。用容器的好处是“即用即弃”配置错了直接docker compose down -v重建不需要反复清理注册表和服务。对开发环境来说这种可丢弃性比性能重要得多。5. VSCode EIDE 的嵌入式交叉开发Touch™ 设备端的最后一公里5.1 从 Touch™ 应用层到 STM32 固件的开发路径Touch™ 除了上位机设备端 SDK 面向 ARM Cortex-M 系列 MCU我这边主力是 STM32F103C8T6 和 RP2040。很多第一次接触这块的人会问“为什么不能只用 Keil”原因很现实Keil MDK 的社区版有编译产物大小限制IAR 需要许可证而 Touch™ 设备端 SDK 在多平台 CI 里默认走 CMake ARM GCC本地用 VSCode EIDE 可以做到同样的构建逻辑不用摇摆于几套 IDE。设备端的经典链路是用 STM32CubeMX 生成基础工程时钟树、GPIO、串口、I2C 触摸芯片配置。把 Touch™ 设备端 SDK 以源码方式加入工程。用 CMake 或 EIDE 构建固件。通过烧录器下载到开发板。如果项目里还需要 FreeRTOSSTM32F103C8T6 这颗芯片只有 20KB RAM移植时要给触摸扫描任务分配足够的栈空间但别贪多。我习惯用 256 字节栈、优先级中等事件队列单独开。痛点往往不是 RTOS 本身而是中断里直接调用 Touch™ 触摸驱动接口导致优先级反转这种问题在裸机上根本不存在换 RTOS 后第一次遇到会懵很久。5.2 VSCode EIDE 具体安装与配置EIDE 这个 VSCode 插件对 Keil 工程兼容性很好也支持 CMake 工程。安装步骤VSCode 扩展市场搜EIDE安装后左侧会出现 EIDE 图标。安装 ARM 交叉编译链可以选择gcc-arm-none-eabi的 10.3-2021.10 releaseWindows 下安装包会带一个.exe装到C:\Program Files (x86)\Arm GNU Toolchain这种路径。在 EIDE 的插件设置里指定工具链路径或者让它在 PATH 里自动找。可以把 Keil 工程直接导入EIDE 左侧选中工程右键Import选择.uvprojx文件。在 VSCode 中让 C/C 插件正确识别头文件路径也很关键。生成一个c_cpp_properties.json把 Touch™ SDK 的 include 目录、CMSIS 目录、HAL 库目录都加进去否则代码里一堆红色波浪线但编译却通过干扰判断{ configurations: [ { name: Win32, includePath: [ ${workspaceFolder}/**, D:/dev/touch-sdk/device/inc, D:/dev/touch-sdk/device/bsp/stm32f1xx/inc, D:/dev/STM32Cube_FW_F1/Drivers/CMSIS/Include ], defines: [STM32F103xB], compilerPath: C:/Program Files (x86)/Arm GNU Toolchain arm-none-eabi/10.3-2021.10/bin/arm-none-eabi-gcc.exe, cStandard: c11, cppStandard: c17 } ], version: 4 }有一个真实踩坑案例EIDE 编译报错arm-none-eabi-gcc: No such file or directory但终端里arm-none-eabi-gcc -v能正常输出。原因不是编译器没装而是 EIDE 插件内部的工具链路径配置还指向旧的 9.x 版本改一下插件设置里的路径就好了。5.3 RP2040 与 Rust 扩展方向Touch™ 环境的多芯片兼容如果你后面打算把 Touch™ 跑在 RP2040 上环境准备类似但有个额外步骤Pico SDK 用子模块方式管理依赖拉取时必须带递归参数git clone --recursive https://github.com/raspberrypi/pico-sdk.gitRP2040 的官方例程用 CMake 编写需要设置PICO_SDK_PATH环境变量。我通常把它加到用户环境变量里避免每个工程重复指定。Touch™ 设备端也在评估 Rust 支持目前 MCU 上的 Rust 工具链是thumbv6m-none-eabi安装命令rustup target add thumbv6m-none-eabi这个后续会成为 Touch™ 的官方支持项但现阶段还是以 C 为主。开发环境早一点把 Rust 工具链配上能减少将来迁移时重新配环境的时间成本。6. 启动失败与运行异常的定位链路从现象到根因的排查顺序6.1 脚本闪退和环境变量不生效的先查顺序我在第二章提过一套脚本闪退排查法这里完整展开把它作为通用方法论。遇到任何“双击没反应”“窗口闪退”的问题按这个顺序走能解决九成避免双击。在终端里手动执行报错信息会留下来。检查执行策略Get-ExecutionPolicy -List确保当前作用域不是 Restricted。检查 PATH 生效状态新开终端执行echo $env:Path看看目标路径是否在列。如果还在列但命令不行用完整路径试一次排除 PATH 写入失败的可能。检查脚本依赖脚本里调用的命令如果来自某个工具链先确认该工具链本身能跑。检查 Windows 安全日志打开“事件查看器”Windows 日志 应用程序看有没有关于脚本的 Error 记录。有些杀毒软件或 Windows Defender 会拦截脚本并留下事件 ID 或软件限制策略相关记录光看弹窗永远不知道是它干的。VSCode 里终端如果打不开或报The terminal process failed to launch排查重点在默认终端的可执行文件路径是否被改动过比如之前配过 Git Bash 的路径更新 Git 后路径失效。6.2 Docker 起不来、端口被占的常见命案现场Docker Desktop 在 Windows 上最常见的启动失败原因是 WSL2 内核组件没更新或虚拟化被关闭。先看这几项wsl --status wsl -l -v如果 WSL2 正常但 Docker Engine 图标一直转圈尝试wsl --shutdown后重启 Docker Desktop。如果还是不行打开“Windows 功能”确认“虚拟机平台”已启。端口被占是另一个高频问题Redis 6379、Elasticsearch 9200 都很容易被本机其他服务占用。定位方式netstat -ano | findstr 6379看到占用进程 PID 后再用tasklist | findstr PID确认是什么程序。如果确认是残留孤儿进程再谨慎地结束。不要随便taskkill /F一个系统服务会有连锁反应。某次我排查 Redis 连不上docker ps显示容器还在运行但客户端就是报Connection refused。最后发现 Docker Desktop 重启后端口映射没恢复容器起来了但端口没有绑定到宿主机。解决方法是docker compose down docker compose up -d让端口映射重新建立。6.3 Elasticsearch 和 Redis 在 Windows 下的启动失败高频原因搜热词“windows启动elasticsearch”时你会看到一堆问题我把常见根因按出现频率列出来现象根因对应解法启动后闪退堆内存设置过大/过小检查 ES_JAVA_OPTS 或 jvm.optionsvm.max_map_count is too lowWSL2 内核参数不足在 WSL2 中 sysctl 调整数据目录权限不足挂载卷属主变化docker compose down -v重建卷9200 端口启动即占用另一个 ES 实例残留netstat 定位后清理Redis 相对简单但有两个坑第一如果容器里设置了密码客户端连接时忘了配 AUTH会一直NOAUTH Authentication required第二Redis 持久化目录如果挂在 Windows 文件系统上比如D:\redis-data性能会明显下降建议挂到 WSL2 内部的 Docker volume 里。6.4 一个完整排查案例新机器装完 Touch™VSCode 找不到编译器最后用一个真实案例把排查链路串一遍。现象新换的工作站环境按 README 装完之后VSCode 打开设备端工程EIDE 点构建报错Program make not found。我的排查过程终端里试make -v也是not recognized。确认问题范围全系统都找不到 make不是 EIDE 单独问题。检查 PATH发现用户变量和系统变量里都没有 GNU Tools 的bin目录。原来 EIDE 安装时提示要装“GNU Arm Embedded Toolchain”装完后安装器没有自动加 PATH。手动把工具链路径加到用户 PATHC:\Program Files (x86)\Arm GNU Toolchain arm-none-eabi\10.3-2021.10\bin。新开终端验证make --version和arm-none-eabi-gcc -v。回 VSCodeEIDE 设置里重新指定工具链路径再构建通过。整个过程看起来不复杂但如果不按顺序排查可能会先怀疑 EIDE 配置、再重装插件最后才意识到是 PATH 的问题白白浪费时间。环境问题永远是“先确认命令在系统层能不能跑再怀疑 IDE 层”。收尾几个让我少踩坑的实操习惯最后分享几个长期积累下来的环境维护习惯。第一我给 Touch™ 开发环境维护了一份 winget 安装清单新机器上直接跑一遍就能恢复八成的工具链。winget 支持导出配置winget export虽然没有原生跨机恢复那么完美但比手动一个个官网下载好太多。第二改动环境变量前先拍一张 PATH 快照。我遇到过几次装了新软件后 PATH 被覆盖老工具全部失效的情况手动恢复非常痛苦。现在我会定期执行echo $env:Path -join n 存成文本方便回溯。第三Windows 下同时维护多套工具链Java、Python、Node、ARM GCC时版本冲突不可避免与其纠结于消除冲突不如明确“哪个项目用哪个版本”这才是 conda、nvm 这类版本管理工具存在的真实意义。这套环境搭好之后Touch™ 的上位机开发和设备端固件开发就能在同一台 Windows 机器上无缝切换中间件用容器随时起停交叉编译链稳定复用。希望这篇经验能让你在搭环境时少耗几个下午。