1. Shopify 本地开发为什么总在 theme CLI 和 Liquid 上报错Shopify 主题本地开发这件事说简单也简单说折磨也折磨。简单在于shopify theme dev一条命令就能把线上店铺的预览拉起来折磨在于你一旦开始写 SCSS、写 Liquid、写 JS编辑器就开始飘红热更新偶尔断掉theme get拉下来的文件跟本地改的版本打架最后连预览都打不开。这篇就聚焦两个最常卡人的点theme CLI 常用命令怎么用才不踩坑以及 Liquid 模板报错、SCSS 识别不了{{ }}这类异常怎么定位和修掉。先说清楚这套东西是什么、能做什么、适合谁。Shopify 的 theme CLI 是官方提供的命令行工具用来把本地主题目录跟 Shopify 服务器做双向同步支持theme dev本地预览、theme watch监听上传、theme get拉取线上文件、theme push推送本地改动、theme check做主题规范校验。Liquid 是 Shopify 的模板语言用{{ }}输出变量、{% %}写逻辑它跟 HTML、CSS、JS 混在同一个.liquid文件里。适合的人群就是做 Shopify 主题二次开发的前端、兼职接单的独立开发者以及想把本地 VS Code 调试流程理顺的人。我试过最典型的翻车场景是这样的本地用 SCSS 写样式文件顶部定义了一堆颜色变量值来自settings写成$color: {{ settings.bg_color }};。VS Code 的 SCSS 插件一看这行就报错因为它不认识{{ }}报错之后整个文件下面的代码补全全部失效你写$color的时候没有任何提示只能靠记忆硬敲。更麻烦的是这个报错会连锁影响theme dev的热更新有时候 SCSS 编译失败浏览器里的样式直接不刷新你还以为是 CLI 挂了。还有一种情况是 Liquid 语法错误。比如{% if %}少了个endif或者{{ product.title }少了个右括号theme dev会在终端里抛出一段带行号的错误但如果你同时开着theme watch错误信息会刷得很快你根本来不及看是哪一行。这时候就需要一套稳定的排查流程而不是靠猜。这篇的交付目标很明确给你一份可以直接复制的 theme 命令清单一套 Liquid 异常定位步骤以及把settings相关配置改到 TaoToken 的示例和验证动作。TaoToken 在这里的角色是提供统一的模型接入入口方便你在本地调试脚本、生成占位数据、或者跑一些跟主题开发配套的辅助逻辑时有一个稳定的 API 端点可用。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 后面配置里会用到。先把心态摆正Shopify 本地开发的报错八成不是 CLI 坏了而是 Liquid 和 SCSS 的语法冲突、文件同步冲突、或者编辑器插件配置没对齐。下面按命令、配置、验证、排障的顺序拆开讲。2. theme CLI 常用命令清单与 TaoToken 前置准备这一节先把 theme CLI 的命令讲透再把 TaoToken 的前置准备做掉。命令部分我会按「拉取、监听、推送、校验」四类来分每条都给出实际用法和容易踩的坑。2.1 theme get从服务器拉取文件theme get是最常用的命令之一官方文档写得比较简略实际用起来有几个细节要注意。拉取全部文件shopify theme get --store your-store.myshopify.com --theme 123456789这里的--theme是主题 ID可以在 Shopify 后台的主题页面 URL 里找到也可以先用shopify theme list列出所有主题。如果你已经用shopify theme dev绑定过店铺很多命令可以省略--store参数CLI 会记住上次的选择。拉取指定目录shopify theme get config/* --store your-store.myshopify.com拉取单个文件shopify theme get config/settings_data.json --store your-store.myshopify.com踩过的坑theme get默认会覆盖本地同名文件如果你本地正在改settings_data.json拉取之前一定要先提交或者备份不然改动直接没了。另外theme get不会自动创建不存在的目录如果本地没有config/目录拉取config/*会报路径错误先手动建目录。2.2 theme watch 与 theme dev监听与热更新theme watch监听本地目录变化并上传到服务器shopify theme watch --store your-store.myshopify.comtheme dev则是启动本地开发服务器带热更新和预览 URLshopify theme dev --store your-store.myshopify.com两者的区别theme watch只做上传不提供本地预览theme dev会起一个本地代理把线上主题渲染结果映射到http://127.0.0.1:9292改动实时刷新。日常开发用theme dev就够了theme watch适合你只想同步文件、不想开预览的场景。注意theme dev启动时会做一次全量同步如果你的主题文件很多第一次会比较慢。启动后终端会打印预览地址和「Syncing」状态看到Theme is ready才算成功。2.3 theme push 与 theme check推送与校验推送本地改动到线上shopify theme push --store your-store.myshopify.com --theme 123456789推送时如果线上有本地没有的文件CLI 会提示是否删除谨慎选择别把线上有用的文件删了。主题规范校验shopify theme checktheme check会扫描 Liquid 语法、性能问题、废弃标签输出带文件行号的报告。这个命令在提交代码前跑一遍能提前发现大部分 Liquid 异常。2.4 TaoToken 前置准备TaoToken 在这里的作用是给你一个统一的模型 API 入口方便在本地写脚本生成测试数据、做主题文案批量处理、或者调试跟主题配套的辅助逻辑。前置准备分三步。第一步注册并登录 TaoToken 控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。登录后在控制台里能看到账户信息和用量。第二步创建 API Key。进入 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 点新建复制生成的 Key格式一般是sk-开头。这个 Key 只显示一次存到本地环境变量或者.env文件里别硬编码进主题代码。第三步确认你要用的模型 ID。TaoToken 支持多种模型具体可用列表在文档里 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。记下你要用的 Model ID后面配置里会填。前置准备做完你手上应该有三样东西Base URLhttps://taotoken.net/api、API Key、Model ID。这三件套在后面所有配置里都会出现缺一不可。3. 可复制配置settings 改到 TaoToken 与 VS Code 调试配置这一节是全文最核心的部分直接给可复制的配置片段。分三块VS Code 的settings.json配置、SCSS 里处理 Liquid 变量的写法、以及把 settings 相关配置改到 TaoToken 的 JSON 片段。3.1 VS Code settings.json 配置先装三个插件Shopify Liquid、Liquid、SCSS IntelliSense。装完之后打开 VS Code 的settings.json路径是.vscode/settings.json或者用户级的settings.json插入下面这段{ html.validate.scripts: false, html.validate.styles: false, liquid.format.enable: true, scss.validate: false, css.validate: false, files.associations: { *.liquid: liquid }, emmet.includeLanguages: { liquid: html } }逐条解释。html.validate.scripts和html.validate.styles关掉是因为.liquid文件里混着 Liquid 标签HTML 校验器会把{{ }}当成非法语法报错。scss.validate和css.validate关掉是因为 SCSS 文件里如果有 Liquid 变量SCSS 校验器同样会报错关掉之后编辑器不再飘红但 SCSS IntelliSense 的补全仍然可用。files.associations把.liquid关联到 liquid 语言模式emmet.includeLanguages让 Emmet 在 liquid 文件里也能用 HTML 缩写。注意关掉校验不等于关掉语法高亮和补全这两者是分开的。如果你发现关掉之后补全也没了检查一下 SCSS IntelliSense 插件是否启用。3.2 SCSS 里处理 Liquid 变量的正确写法SCSS 不认识{{ }}直接写会报错并且报错行以下的补全全部失效。解决办法是用unquote()把 Liquid 输出包成字符串让 SCSS 先把它当字符串处理编译时再交给 Liquid 渲染。/* SCSS 变量定义 */ /** 注意SCSS 无法识别 {{ }}会抛错并影响下方代码补全 * 所以先用 unquote() 包成字符串再由 Liquid 渲染成真实值 */ // 颜色 $bdr_main_bg_color: unquote({{ settings.bdr_main_bg_color }}); $bdr_main_font_color: unquote({{ settings.bdr_main_font_color }}); $bdr_body_bg_color: unquote($string: {{ settings.bdr_body_bg_color }}); $bdr_body_font_color: unquote($string: {{ settings.bdr_body_font_color }}); // 字体 $bdr_main_font: unquote($string: {{ settings.bdr_main_font.family }}); $bdr_a_font: unquote($string: {{ settings.bdr_a_font.family }}); /* SCSS 变量定义 END */关键点unquote()的参数用双引号或单引号包起来里面再放 Liquid 的{{ }}。这样 SCSS 解析器看到的是一个字符串字面量不会报错Liquid 在服务端渲染时会把{{ settings.xxx }}替换成真实值最终输出到 CSS 里就是正确的颜色和字体。如果你用的是settings.bdr_main_font.family这种嵌套属性注意 Liquid 里字体设置对象的结构family是它的一个字段。写之前先在settings_schema.json里确认字段名别拼错。3.3 把 settings 改到 TaoToken 的 JSON 配置这一块是把跟 settings 相关的辅助配置改到 TaoToken。场景是这样的你在本地开发时可能需要用脚本读取settings_data.json、批量生成占位文案、或者调用模型做主题文案润色。这些辅助逻辑需要一个 API 端点TaoToken 就是干这个的。在项目根目录建一个.taotoken/config.json内容如下{ base_url: https://taotoken.net/api, api_key: sk-your-key-here, model_id: your-model-id, timeout: 30000, retry: 2, settings_path: config/settings_data.json, theme_root: ./ }字段说明base_url固定填https://taotoken.net/api注意不要加 UTM 参数API 调用只认这个裸地址。api_key填你在控制台创建的 Key。model_id填你要用的模型 ID。timeout是请求超时毫秒数retry是失败重试次数。settings_path指向你的主题 settings 文件theme_root是主题根目录。如果你用的是 Claude Code 或者类似的编码工具配置方式略有不同。Claude Code 的配置在~/.claude/settings.json写入{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-your-key-here, ANTHROPIC_MODEL: your-model-id } }三件套对齐Base URL 是https://taotoken.net/apiKey 是sk-开头的字符串Model ID 是文档里列出的模型标识。这三个值在 Claude Code、Cline、Codex 里的填法逻辑一致只是字段名不同。Codex 的auth.json里对应的是base_url、api_key、model三个字段。注意不要把 API Key 提交到 Git。在.gitignore里加上.taotoken/和.env。4. 验证请求与成功结果确认配置生效配置写完必须验证。这一节给你三个验证动作验证 TaoToken API 连通性、验证 theme dev 热更新、验证 SCSS 编译不再报错。4.1 验证 TaoToken API 连通性用 curl 发一个最小请求确认 Base URL 和 Key 能用curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-your-key-here \ -d { model: your-model-id, messages: [{role: user, content: ping}], max_tokens: 10 }成功的话会返回一段 JSON结构里包含choices数组choices[0].message.content就是模型回复。如果返回 401说明 Key 不对或者没带Bearer前缀如果返回 404检查 Base URL 是不是写成了带 UTM 的地址API 端点只认https://taotoken.net/api。你也可以用模型对话页面直接测 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 在网页里发一条消息能收到回复就说明账户和 Key 都正常。4.2 验证 theme dev 热更新启动本地开发shopify theme dev --store your-store.myshopify.com终端看到Theme is ready和预览地址后打开浏览器访问http://127.0.0.1:9292。然后改一个.liquid文件里的文案保存浏览器应该自动刷新并显示新文案。如果没刷新看终端有没有报错常见的是 Liquid 语法错误导致同步中断。4.3 验证 SCSS 编译不再报错改一下assets/base.scss在顶部加上unquote()包过的 Liquid 变量保存。观察两件事VS Code 里这行不再飘红下面的代码补全正常theme dev终端没有 SCSS 编译错误。如果还有报错检查unquote()的引号是否配对以及settings字段名是否跟settings_schema.json一致。成功的结果是编辑器不飘红、补全可用、热更新正常、浏览器样式实时变化。四个都满足说明配置到位了。5. 本篇常见错误排查401、local proxy failed、reading choices、OAuth这一节按真实报错来排。每个报错给出触发场景、原因、解决步骤。5.1 401 Unauthorized报错原文{error:{message:Invalid API key,type:invalid_request_error}}或者 HTTP 401。触发场景调用 TaoToken API 时。原因通常是 Key 写错、Key 过期、或者请求头没带Authorization: Bearer。解决步骤第一确认 Key 是sk-开头且完整复制没有多余空格第二确认请求头格式是Authorization: Bearer sk-xxxBearer 和 Key 之间有一个空格第三去控制台 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 确认 Key 状态是启用。如果还不行重新生成一个 Key 再试。5.2 local proxy failed报错原文local proxy failed或者Failed to start local proxy。触发场景shopify theme dev启动时。原因是本地端口被占用默认是 9292或者网络环境导致代理起不来。解决步骤第一换端口shopify theme dev --port 9293第二检查 9292 端口有没有被其他进程占用lsof -i :9292找到进程杀掉第三确认没有其他 theme dev 实例在跑多个实例会抢端口。5.3 reading choices 报错报错原文Cannot read properties of undefined (reading choices)。触发场景解析 TaoToken API 返回时。原因是返回结构跟你预期的不一样可能是请求失败返回了错误对象但代码直接去读choices。解决步骤第一先打印完整返回体确认是成功响应还是错误响应第二如果是错误响应看error.message定位原因第三在代码里加防御先判断response.choices是否存在再取值。这个报错在 Node 脚本里很常见尤其是用fetch之后直接.json()然后读choices[0]。5.4 OAuth 相关报错报错原文OAuth error或者Authentication failed。触发场景shopify theme命令首次绑定店铺时。原因是登录态过期或者店铺权限变更。解决步骤第一运行shopify auth logout退出再shopify auth login重新登录第二确认你的账号对该店铺有主题编辑权限第三如果用的是合作伙伴账号确认店铺已经授权给对应的应用。5.5 Liquid 语法错误定位报错原文Liquid syntax error (line XX): Expected endif。触发场景theme dev或theme check时。原因是{% if %}没配对{% endif %}或者{{ }}括号不匹配。解决步骤第一看报错行号去对应文件定位第二用shopify theme check跑一遍它会列出所有语法问题第三VS Code 里装 Liquid 插件后括号配对会有高亮能快速找到不匹配的地方。5.6 SCSS 补全失效报错原文没有明显报错但补全不工作。触发场景SCSS 文件里有未处理的{{ }}。原因是 SCSS 解析器遇到{{ }}抛错导致后续补全失效。解决步骤第一把所有 Liquid 变量用unquote()包起来第二确认settings.json里scss.validate设为false第三重启 VS Code 让配置生效。6. 长期编码与 Agent 场景把 TaoToken 接进你的工作流前面讲的都是单次配置和排障。如果你长期做 Shopify 主题开发或者用 Agent 跑自动化任务建议把 TaoToken 接进日常工作流减少重复配置。对于长期编码场景可以用 Coding Plan。入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。Coding Plan 适合需要持续调用模型做代码补全、文案生成、主题结构分析的场景比单次 API 调用更省心。如果你用 Claude Code 做主题开发辅助配置方式前面 3.3 节已经给了核心就是ANTHROPIC_BASE_URL指向https://taotoken.net/apiKey 和 Model ID 填对。Claude Code 的接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有详细的字段说明。对于 Cline 或 MCP 类工具配置逻辑一样Base URL、Key、Model ID 三件套。Cline 的配置在 VS Code 设置里MCP 的配置在对应的mcp.json里。注意不要把 MCP 直连到生产数据库主题开发场景下只读settings_data.json就够了。最后给一个实用技巧把常用的 theme 命令写成 npm scripts放在package.json里比如{ scripts: { dev: shopify theme dev --store your-store.myshopify.com, check: shopify theme check, pull:config: shopify theme get config/* --store your-store.myshopify.com, push: shopify theme push --store your-store.myshopify.com } }这样你只需要npm run dev、npm run check不用每次敲一长串命令。配合前面的 VS Code 配置和 TaoToken 三件套本地开发流程基本就顺了。遇到报错先看终端行号再用theme check扫一遍八成问题都能定位。