这份文档面向第一次打开 Fdesign 的国内用户，目标是在 10 分钟内判断三件事：
- 项目是否能在本机启动。
- 后端和前端是否能互相访问。
- 公开演示包的字段映射是否看得懂。
它不要求你一开始就拿真实 PSD 模板测试。真实模板、真实商品图和未净化字段请先留在本地，等基础链路跑通后再逐步接入。
请先确认：
- Windows 10/11 x64。
- Node.js 18 或更高版本。
- 本机已安装 Adobe Photoshop，并且可以正常手动打开。
- 仓库路径不要放在权限很高或同步盘冲突明显的位置，建议先放在普通英文路径，例如
D:\Projects\Fdesign。
检查命令：
node -v
npm -v如果国内网络安装依赖较慢，可以先使用镜像源：
npm config set registry https://registry.npmmirror.comgit clone https://github.com/Kriswd/Fdesign.git
cd Fdesign
npm install如果 npm install 失败，先记录完整错误，再确认：
- Node.js 版本是否满足要求。
- 当前目录是否有写入权限。
- 防火墙或代理是否拦截 npm 下载。
- 终端是否在项目根目录，也就是能看到
package.json的目录。
打开第一个 PowerShell 窗口：
npm run server后端默认健康检查地址：
http://127.0.0.1:3001/health
浏览器打开后应该能看到 JSON 响应，并包含版本信息。当前开源版本应显示 3.0。
保留后端窗口不要关闭，再打开第二个 PowerShell 窗口：
cd Fdesign
npm run dev前端默认访问地址：
http://127.0.0.1:3010/
如果端口被占用，先关闭旧的本地服务，或根据终端提示使用新的端口。
第一次不要急着上传真实模板。建议先打开：
重点看懂这条关系：
Excel 列 -> PSD 文本变量 / 图片变量 -> 导出命名
演示包只包含净化数据和 SVG 示例图，不包含私有 PSD 模板、真实商品素材或导出产物。
基础服务启动后，建议先按 最小 PSD 模板制作教程 做一个很小的 PSD 测试模板：
- 一个文本变量，例如款号。
- 一个文本变量，例如色号。
- 一个图片占位层，例如主图。
- 先只跑一条 Excel 记录。
单条记录能稳定导出后，再增加更多变量、规则链和批量数据。
- 确认
npm run server窗口没有报错。 - 确认访问的是
http://127.0.0.1:3001/health。 - 确认 3001 端口没有被其它程序占用。
- 确认
npm run dev窗口还在运行。 - 优先使用终端打印出的本地地址。
- 如果浏览器缓存异常，换无痕窗口或刷新页面。
- 先手动打开 Photoshop，确认它没有卡在登录、更新、弹窗或授权页面。
- 确认 PSD 文件没有被其它程序锁定。
- 确认导出目录可写。
- 复杂模板先减到最小变量集合，只跑一条记录。
- 检查 Excel 中的图片路径是否真实存在。
- 检查款号、色号、角度命名是否和图片文件名一致。
- 检查 PSD 图片变量是否绑定到了正确字段。
如果你愿意反馈，请优先提供净化后的信息：
- Windows、Node.js、Photoshop 版本。
- 最短复现步骤。
- 净化后的字段名、变量名、错误提示。
- 不包含真实商品图、账号信息、未净化字段或私有 PSD 的截图。
可以直接复制这个 30 秒模板：
我从哪里看到 Fdesign：
我想跑的流程：主图多色号 / 多画板详情页 / 字段组合 / 其他
运行到哪一步：npm 安装 / 后端健康检查 / 前端打开 / Photoshop 导出 / 图片匹配
环境：Windows 版本、Node.js 版本、Photoshop 版本
净化后的 PSD 结构：例如 Hero/{img:main}、Specs/{text:model}
净化后的 Excel 字段：例如 款号、色号、镜框颜色、镜片颜色
净化后的图片命名：例如 FDX1001-C10-front.png
报错摘要：贴 5-20 行关键错误或页面提示
期望结果：想批量导出 PSD / PSB / PNG / JPEG 中的哪些格式
反馈入口：
如果你已经完成前后端启动，并看懂了公开演示包：
- 回到 GitHub 仓库 点一个 Star，方便后面继续找到项目。
- 如果首次启动有卡点，跟进 首次试跑反馈 #7。
- 如果你的 PSD 结构、Excel 字段或图片命名规则不确定能否适配，跟进 PSD 适配反馈 #17。
- 如果你愿意贡献可公开复现的流程，跟进 净化案例征集 #2，只使用假数据、公开截图和净化字段。