Upscayl Windows 本地构建从环境自查到打包成功的实战手册【免费下载链接】upscayl Upscayl - #1 Free and Open Source AI Image Upscaler for Linux, MacOS and Windows.项目地址: https://gitcode.com/GitHub_Trending/up/upscayl本文带你完成 Upscayl 的 Windows 本地构建先用自查清单排除环境与硬件隐患再走通「清理 → 编译 → electron-builder 打包」的标准流程最后用一份症状对照表定位 Vulkan 初始化失败、electron-builder 找不到、资源文件缺失这类高频报错。构建前自查清单先排除这些隐患系统与硬件自查动手前先逐项核对任何一项不达标后面的报错都可能只是表象Windows 10/11 64 位系统GPU 支持 Vulkan官方在 README.md 中明确提示放大功能依赖 Vulkan 兼容显卡不少核显不工作可用内存 ≥ 8GB磁盘剩余空间 ≥ 5GBNode.js 版本与项目锁定版本一致见下文关于 GPU 一项可以用 VulkanCapsViewer 这类工具跑一次确认显卡能正常初始化 Vulkan驱动较老的机器建议先更新驱动再谈构建。为什么 Node 版本必须对上package.json 里通过 Volta 把 Node 钉死在18.20.5。这不是随意选的项目依赖的 electron-builder 25.x 和 Next.js 15.x 都与该版本配套验证过。你本机 Node 版本偏新或偏旧时构建可能在安装依赖或打包阶段冒出各种诡异的兼容报错——版本错位是初学者最常踩的第一个坑。环境准备五分钟装齐工具链安装# 让 Node 版本跟随项目锁定推荐 Voltanvm 同理 volta install node一行命令把 Node 对齐到 18.20.5省去手动对版本号的麻烦。拉代码与装依赖git clone https://gitcode.com/GitHub_Trending/up/upscayl cd upscayl npm installnpm install会拉下 electron-builder、next、react 等全部依赖耗时几分钟耐心等它结束中途断开会导致 node_modules 不完整后文会讲怎么修。标准构建流程一条命令到产出物标准命令序列npm run clean删掉旧的dist和renderer/.next、renderer/out防止残留产物干扰判断。npm run tsc编译 TypeScript类型错误在这一步就会暴露出来。npm run dist:win这是 Windows 构建的核心命令内部依次执行 tsc、schema 校验、Next.js 前端构建最后交给 electron-builder 打包。怎么算构建成功构建跑完后dist/目录artifactName 按${name}-${version}-${os}命名应出现当前版本2.15.0对应的文件upscayl-2.15.0-win.exe—— NSIS 安装程序upscayl-2.15.0-win.zip—— 便携版压缩包构建日志中能看到关键行即说明打包进入尾声• building block map • building targetnsis filedist/upscayl-2.15.0-win.exe archsx64 • building targetzip filedist/upscayl-2.15.0-win.zip archsx64没有产物生成、也没有报错通常是上一步的 npm 依赖或资源文件出了问题直接查下一节。报错自查手册症状对照与重点排查症状 → 处理动作对照表症状最可能原因自查动作Failed to initialize Vulkan等 Vulkan 初始化失败驱动缺失/过旧、核显不支持 Vulkan、双显卡切换混乱见下文重点一electron-builder 不是内部或外部命令node_modules 安装不完整见下文重点二ENOENT ... resources/win/bin/upscayl-bin.exencnn 运行时二进制未就位见下文重点三构建完成但 dist 里没有任何 exe前端构建阶段静默失败单独跑npm run build看真实报错应用启动后闪退、无日志缺少 VC 运行库或 GPU 调度冲突安装 VC 运行库参考 docs/troubleshooting/windows.mdx 中「DirectX repair」与「启用硬件加速 GPU 调度」两条重点一Vulkan 初始化失败症状识别放大图片时提示 Vulkan 相关错误进程随后中断。处理步骤① 用 VulkanCapsViewer 确认显卡确实在 Vulkan 设备列表中② 重装显卡驱动③ 双显卡笔记本尽量关闭混合输出switchable graphics或在设置面板的 GPU ID 输入框手动指定正确的显卡编号如何看 ID 参考 docs/Guide.md 的 GPU ID 一节。如何验证重新放大一张图日志区域能列出可用的 GPU ID 且任务跑完即通过。重点二electron-builder 找不到症状识别跑npm run dist:win时提示命令不存在。处理步骤清掉损坏的依赖重装npm cache clean --force # 删除 node_modules 与 package-lock.json 后 npm install如何验证npx electron-builder --version能打印版本号说明工具链已就位重跑npm run dist:win即可。重点三资源文件缺失症状识别打包阶段报ENOENT: no such file or directory, open resources/win/bin/upscayl-bin.exe。处理步骤electron-builder 的extraFiles配置会把resources/win/bin整体拷入安装包但仓库默认不带这些二进制。项目根目录的 update_upscayl_ncnn_binaries.sh 会拉取最新版 ncnn 运行时并放置upscayl-bin.exe与vcomp140.dll、vcomp140d.dll到resources/win/bin/。该脚本是 bash 脚本需在 Git Bash 或 WSL 中执行网络受限也可按脚本逻辑手动下载对应 zip 放入该目录。如何验证确认resources/win/bin/upscayl-bin.exe存在后重跑npm run dist:win打包不再报 ENOENT。构建成功后还要做的三件事核对产物与日志确认dist/下 exe 与 zip 体积正常MB 级日志末尾无error字样。跑一次冒烟测试安装 exe打开应用用 ups/to_upscale.jpeg 这类小图走一遍「选图 → 选模型 → 放大」全流程能输出结果图即核心链路正常。拿到并看懂日志应用内切到 Settings 标签页LOGS 区域实时显示主进程日志点COPY LOGS一键复制完整日志入口逻辑见 electron/utils/logit.ts报问题前先贴日志效率最高。可选优化包更小、构建更快npm run pack-apptsc 前端构建 electron-builder --dir只打目录不出安装程序迭代验证阶段快很多代价是得不到最终 exe发布前仍要跑完整命令。调整 package.json 中files/extraFiles排除用不到的资源包会明显变小代价是每加一条 filter 都得回归测试确认没误伤运行时必需文件。cross-env DEBUG* electron-builder即npm run dist输出全量调试日志排错时信息更全代价是构建输出变长、略慢日常构建不建议常开。还是搞不定怎么办先翻官方文档docs/troubleshooting/windows.mdx 列了 DirectX repair、关闭混合输出、启用硬件加速 GPU 调度等 Windows 专项建议docs/troubleshooting/logs.mdx 讲日志的获取与分享方式。提 issue 时务必附三样项目版本号package.json中的 version、系统环境Windows 版本 显卡型号 Node 版本、COPY LOGS复制的完整日志。缺了日志的 issue 很难定位。 小习惯每次构建前先git pull拉最新代码能直接绕开一批已修复的构建问题。【免费下载链接】upscayl Upscayl - #1 Free and Open Source AI Image Upscaler for Linux, MacOS and Windows.项目地址: https://gitcode.com/GitHub_Trending/up/upscayl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Upscayl Windows 本地构建：从环境自查到打包成功的实战手册
Upscayl Windows 本地构建从环境自查到打包成功的实战手册【免费下载链接】upscayl Upscayl - #1 Free and Open Source AI Image Upscaler for Linux, MacOS and Windows.项目地址: https://gitcode.com/GitHub_Trending/up/upscayl本文带你完成 Upscayl 的 Windows 本地构建先用自查清单排除环境与硬件隐患再走通「清理 → 编译 → electron-builder 打包」的标准流程最后用一份症状对照表定位 Vulkan 初始化失败、electron-builder 找不到、资源文件缺失这类高频报错。构建前自查清单先排除这些隐患系统与硬件自查动手前先逐项核对任何一项不达标后面的报错都可能只是表象Windows 10/11 64 位系统GPU 支持 Vulkan官方在 README.md 中明确提示放大功能依赖 Vulkan 兼容显卡不少核显不工作可用内存 ≥ 8GB磁盘剩余空间 ≥ 5GBNode.js 版本与项目锁定版本一致见下文关于 GPU 一项可以用 VulkanCapsViewer 这类工具跑一次确认显卡能正常初始化 Vulkan驱动较老的机器建议先更新驱动再谈构建。为什么 Node 版本必须对上package.json 里通过 Volta 把 Node 钉死在18.20.5。这不是随意选的项目依赖的 electron-builder 25.x 和 Next.js 15.x 都与该版本配套验证过。你本机 Node 版本偏新或偏旧时构建可能在安装依赖或打包阶段冒出各种诡异的兼容报错——版本错位是初学者最常踩的第一个坑。环境准备五分钟装齐工具链安装# 让 Node 版本跟随项目锁定推荐 Voltanvm 同理 volta install node一行命令把 Node 对齐到 18.20.5省去手动对版本号的麻烦。拉代码与装依赖git clone https://gitcode.com/GitHub_Trending/up/upscayl cd upscayl npm installnpm install会拉下 electron-builder、next、react 等全部依赖耗时几分钟耐心等它结束中途断开会导致 node_modules 不完整后文会讲怎么修。标准构建流程一条命令到产出物标准命令序列npm run clean删掉旧的dist和renderer/.next、renderer/out防止残留产物干扰判断。npm run tsc编译 TypeScript类型错误在这一步就会暴露出来。npm run dist:win这是 Windows 构建的核心命令内部依次执行 tsc、schema 校验、Next.js 前端构建最后交给 electron-builder 打包。怎么算构建成功构建跑完后dist/目录artifactName 按${name}-${version}-${os}命名应出现当前版本2.15.0对应的文件upscayl-2.15.0-win.exe—— NSIS 安装程序upscayl-2.15.0-win.zip—— 便携版压缩包构建日志中能看到关键行即说明打包进入尾声• building block map • building targetnsis filedist/upscayl-2.15.0-win.exe archsx64 • building targetzip filedist/upscayl-2.15.0-win.zip archsx64没有产物生成、也没有报错通常是上一步的 npm 依赖或资源文件出了问题直接查下一节。报错自查手册症状对照与重点排查症状 → 处理动作对照表症状最可能原因自查动作Failed to initialize Vulkan等 Vulkan 初始化失败驱动缺失/过旧、核显不支持 Vulkan、双显卡切换混乱见下文重点一electron-builder 不是内部或外部命令node_modules 安装不完整见下文重点二ENOENT ... resources/win/bin/upscayl-bin.exencnn 运行时二进制未就位见下文重点三构建完成但 dist 里没有任何 exe前端构建阶段静默失败单独跑npm run build看真实报错应用启动后闪退、无日志缺少 VC 运行库或 GPU 调度冲突安装 VC 运行库参考 docs/troubleshooting/windows.mdx 中「DirectX repair」与「启用硬件加速 GPU 调度」两条重点一Vulkan 初始化失败症状识别放大图片时提示 Vulkan 相关错误进程随后中断。处理步骤① 用 VulkanCapsViewer 确认显卡确实在 Vulkan 设备列表中② 重装显卡驱动③ 双显卡笔记本尽量关闭混合输出switchable graphics或在设置面板的 GPU ID 输入框手动指定正确的显卡编号如何看 ID 参考 docs/Guide.md 的 GPU ID 一节。如何验证重新放大一张图日志区域能列出可用的 GPU ID 且任务跑完即通过。重点二electron-builder 找不到症状识别跑npm run dist:win时提示命令不存在。处理步骤清掉损坏的依赖重装npm cache clean --force # 删除 node_modules 与 package-lock.json 后 npm install如何验证npx electron-builder --version能打印版本号说明工具链已就位重跑npm run dist:win即可。重点三资源文件缺失症状识别打包阶段报ENOENT: no such file or directory, open resources/win/bin/upscayl-bin.exe。处理步骤electron-builder 的extraFiles配置会把resources/win/bin整体拷入安装包但仓库默认不带这些二进制。项目根目录的 update_upscayl_ncnn_binaries.sh 会拉取最新版 ncnn 运行时并放置upscayl-bin.exe与vcomp140.dll、vcomp140d.dll到resources/win/bin/。该脚本是 bash 脚本需在 Git Bash 或 WSL 中执行网络受限也可按脚本逻辑手动下载对应 zip 放入该目录。如何验证确认resources/win/bin/upscayl-bin.exe存在后重跑npm run dist:win打包不再报 ENOENT。构建成功后还要做的三件事核对产物与日志确认dist/下 exe 与 zip 体积正常MB 级日志末尾无error字样。跑一次冒烟测试安装 exe打开应用用 ups/to_upscale.jpeg 这类小图走一遍「选图 → 选模型 → 放大」全流程能输出结果图即核心链路正常。拿到并看懂日志应用内切到 Settings 标签页LOGS 区域实时显示主进程日志点COPY LOGS一键复制完整日志入口逻辑见 electron/utils/logit.ts报问题前先贴日志效率最高。可选优化包更小、构建更快npm run pack-apptsc 前端构建 electron-builder --dir只打目录不出安装程序迭代验证阶段快很多代价是得不到最终 exe发布前仍要跑完整命令。调整 package.json 中files/extraFiles排除用不到的资源包会明显变小代价是每加一条 filter 都得回归测试确认没误伤运行时必需文件。cross-env DEBUG* electron-builder即npm run dist输出全量调试日志排错时信息更全代价是构建输出变长、略慢日常构建不建议常开。还是搞不定怎么办先翻官方文档docs/troubleshooting/windows.mdx 列了 DirectX repair、关闭混合输出、启用硬件加速 GPU 调度等 Windows 专项建议docs/troubleshooting/logs.mdx 讲日志的获取与分享方式。提 issue 时务必附三样项目版本号package.json中的 version、系统环境Windows 版本 显卡型号 Node 版本、COPY LOGS复制的完整日志。缺了日志的 issue 很难定位。 小习惯每次构建前先git pull拉最新代码能直接绕开一批已修复的构建问题。【免费下载链接】upscayl Upscayl - #1 Free and Open Source AI Image Upscaler for Linux, MacOS and Windows.项目地址: https://gitcode.com/GitHub_Trending/up/upscayl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考