Beginner guide · Screenshot walkthrough

从零创建一个京东小程序

使用 Taro 多端框架，通过命令行完成项目初始化，再把编译产物导入微信开发者工具，跑通第一个小程序项目。

Taro 4.2.1ReactTypeScriptSassVite
学习地图

这套截图讲的是一条完整的“从命令到预览”链路

你可以把它理解为：创建源码项目 → 安装依赖 → 编译成小程序文件 → 用微信开发者工具打开 → 在模拟器中看到页面。

终端→Taro 项目→npm install→dist→微信开发者工具
28 张原始操作截图已全部保留
7 个阶段适合按顺序边看边操作
1 个核心命令npx @tarojs/cli init 项目名
1 个产物目录dist/ 是导入微信工具的关键

1准备工作：打开项目所在目录

先新建一个用于存放项目的文件夹（示例中是 mini），在这个文件夹里打开终端。这样执行初始化命令后，项目会创建在当前目录下。

建议：目录路径尽量使用英文、数字和短横线，避免空格、中文路径导致工具链或脚本兼容性问题。
打开工作目录在项目父目录中打开终端。
终端就位确认提示符已经位于目标文件夹。
先查文档Taro 安装页说明了 Node 与 CLI 要求。
项目初始化说明文档中给出了 taro init myApp 与 npx @tarojs/cli init myApp 两种方式。

2初始化：用 CLI 创建 Taro 项目

使用 npx 可以直接调用 Taro CLI，不必先全局安装。把 demo 换成你的项目名。

npx @tarojs/cli init demo

按向导逐项选择

截图中的选择组合是：React、TypeScript、ES5、Sass、npm、Vite，然后选择模板源。

  • 项目介绍：随便填写即可，不影响项目创建。
  • 框架：选择 React。
  • TypeScript：选择 Yes，更适合后续维护。
  • ES5：需要兼容旧环境时选择 Yes。
  • CSS 预处理器：选择 Sass。
  • 包管理工具：选择 npm；编译工具：选择 Vite。
  • 模板源：示例选择 Gitee（最快），模板可以按项目需要调整。
输入初始化命令替换项目名称。
填写项目介绍内容可自定义。
选择 React方向键选择后回车确认。
启用 TypeScript输入 y 或选择 Yes。
启用 ES5按项目兼容性决定。
选择 Sass作为 CSS 预处理器。
选择 npm依赖安装工具。
选择 Vite作为编译工具。
选择模板源示例使用 Gitee。
拉取模板等待模板仓库下载完成。
选择具体模板初学者可选默认模板。

3安装依赖：失败也不必慌

初始化完成后，工具会执行 npm install。截图中第一次安装失败，随后通过 Claude Code 检查项目结构、更新 npm 镜像并处理 React Refresh 版本冲突，最终安装了 1016 个包并构建成功。

看到红色报错怎么办？
先看错误是否发生在“安装依赖”阶段；确认 npm 源、Node 版本和 package.json 依赖版本，再重新安装。不要一上来就用 --force 覆盖冲突。
初始化后安装失败项目文件已生成，但依赖安装需要重试。
启动辅助机器人让工具检查依赖与冲突。
让机器人理解项目要求先了解项目并安装依赖。
分析并修复发现旧 npm 源与版本不匹配问题。
验证通过安装 1016 个包，构建通过。

4打开项目：认识源码结构

用 IDEA 等编辑器打开新生成的项目目录。截图中的项目技术栈为 Taro 4.2.1 + React 18 + TypeScript + Sass，模板为 youshu。

重点看哪里： src/ 放源码，src/pages/index 是示例页面，config/ 放环境配置，package.json 记录脚本和依赖，dist/ 是编译后产物。
找到项目目录在 IDEA 中打开刚刚生成的 demo 项目。
IDEA 识别项目查看 package.json 中的构建脚本和依赖。

5编译：生成微信小程序的 dist

在 IDEA 中运行 build:weapp，Taro 会把 React/TS 源码转换为微信小程序可以识别的 JS、WXML、JSON 等文件。

npm run build:weapp

看到 Process finished with exit code 0，并且输出中出现 built in ...s，就表示打包完成。

选择项目目录在 IDEA 的项目列表或打开对话框中找到 demo。
运行 build:weapp构建成功后会生成 dist。

6导入微信开发者工具

打开微信开发者工具，选择“小程序 → 导入项目”，项目目录选择刚刚生成的 demo/dist，不要选源码根目录。

  1. 项目名称：可填 dist 或自定义名称。
  2. 目录：选择绝对路径下的 dist 文件夹。
  3. AppID：填入你准备好的小程序 AppID；没有时可先使用测试号或不使用云服务。
  4. 点击“创建”，首次运行遇到“是否信任项目”时选择“信任并运行”。
AppID 报错不等于项目代码错。
游客服 AppID 不能使用某些能力；如果只是本地学习，可以先选择测试号或不使用云服务。
导入 dist在导入项目窗口选择编译产物目录。
填写 AppID使用已准备好的小程序号。
信任并运行允许开发者工具运行项目。

7验证结果：看到页面就成功了一半

开发者工具左侧会显示 DIST 文件，右侧模拟器能够渲染出页面。截图中的示例页面显示了 “Hello world!”。

到这里，项目创建链路就完成了。接下来就可以继续修改 src/pages/index 页面、配置路由和接入小程序能力。

模拟器预览页面能显示，说明编译和导入链路已经跑通。
最后检查清单

初学者最容易卡住的 5 个点

  • 目录选错：微信开发者工具要导入 dist，不是项目根目录。
  • 路径复杂：项目路径尽量不要出现中文、空格或特殊字符。
  • 依赖安装失败：检查 npm 源、Node 版本和版本冲突，安装成功后再构建。
  • AppID 不可用：使用测试号或关闭云服务进行本地学习。
  • 控制台有红字：先看右侧模拟器是否正常显示；部分网络域名或统计日志提示不影响页面预览。