LlamaCoder：用一句提示词生成单文件 Web 应用的开源 Claude Artifacts 平替｜部署与使用全指南
适用读者：想本地/自建一套"输入一句话、直接吐出可运行单页应用"工具链的开发者、想脱离闭源 Artifacts 服务自己掌控模型与数据的 AI 应用爱好者、以及想研究 Artifacts 式前端代码沙盒是怎么实现的同学。本文所有命令、环境变量、依赖版本均来自官方 GitHub README 与 package.json，可直接照做；项目许可证为 MIT。
一、项目简介
LlamaCoder 是一个开源的"Claude Artifacts 平替"：在输入框里用自然语言描述你想要的小应用（比如"给我做一个记账 App"），它就调用大模型生成一段完整的前端代码，并在浏览器里直接沙盒预览、可继续对话迭代。官方 README 一句话定位是："An open source Claude Artifacts – generate small apps with one prompt. Powered by Llama 3 on Together.ai."（一个开源的 Claude Artifacts——用一条提示词生成小应用，由 Together.ai 上的 Llama 模型驱动。）
核心信息一览
| 项目 | 内容 |
|---|---|
| 官方仓库 | https://github.com/Nutlope/llamacoder |
| 在线体验 | https://www.llamacoder.io |
| 许可证 | MIT（Copyright (c) 2024 Hassan El Mghari） |
| 大模型 | Llama 3.1 405B（Meta），经 Together AI 推理 |
| 技术栈 | Next.js（app router）+ Tailwind CSS + esbuild-wasm + esm.sh |
| 可观测性 | Braintrust（可选）+ Plausible 统计 |
| 当前版本号 | package.json 中为 0.1.0，框架依赖 Next.js 16.3.8、React 19.2.9 |
仓库归属说明：任务清单里写的
togethercomputer/llamaco实际已 404，并不存在；LlamaCoder 的官方仓库在作者 Hassan El Mghari（GitHub ID：Nutlope）名下，Together AI 是它调用的模型推理服务商，而非仓库 owner。本文以可核实的Nutlope/llamacoder为准。
适用场景
- 快速把一个点子（落地页、小工具、数据可视化、小游戏、个人作品集）变成可在浏览器里跑的单页原型；
- 学习"提示词→前端代码→沙盒预览"这一套 Artifacts 式交互是怎么拼起来的；
- 想要自己替换成任意兼容 OpenAI 风格的模型接口，而不是被锁死在某家闭源 Artifacts 服务里；
- 给团队做一个可自托管的内部"点子快速变原型"小工具。
能力边界（务必先读）
- 它生成的是单文件/小型前端应用，跑在浏览器沙盒 iframe 里，不是完整的全栈工程，也不帮你管理后端与数据库；
- 强依赖一个外部 LLM 推理接口（默认 Together AI）和一个PostgreSQL 数据库（官方推荐 Neon），并非"clone 下来零配置就能跑"；
- 它本身不自带模型权重，README 给出的默认链路是云端 Together API；想完全本地离线跑，需要自行把推理层改造成对接 Ollama 等本地服务；
- 生成代码质量取决于所选模型与提示词，官方默认提供"质量/速度"档位切换（Low quality [faster]），别指望一句话产出生产级工程。
二、功能特性
- 一条提示词生成小应用：输入自然语言需求，模型输出可直接运行的前端代码，边聊边改；
- 浏览器内沙盒预览：用
esbuild-wasm+esm.sh在一个被沙盒隔离的 iframe 里实时编译并渲染预览，无需本地再起一个后端就能看到效果； - Next.js App Router + Tailwind：项目本身用现代前端栈搭建，UI 与路由结构清晰，二次开发门槛低；
- 模型可换、档位可调：默认走 Together AI 上的 Llama 3.1 405B，界面里可切生成质量档位，接口形态兼容主流 LLM 接入方式，方便替换成其他模型；
- 截图上传：支持把生成结果截图上传存档，依赖 S3 兼容对象存储；
- 观测与统计：可选 Braintrust 做模型调用观测，Plausible 做站点访问统计。
技术栈为什么这么选（来自官方 README，帮助你判断好不好二次开发）：
- 模型层用 Meta 的 Llama 3.1 405B、跑在 Together AI 上，好处是不用自己买显卡就能拿到大参数模型；
- 预览层不用起 Node 后端，而是把
esbuild-wasm拉进浏览器，再从esm.sh按需取依赖，在沙盒 iframe 里即时编译运行——这正是它能"生成即预览"的关键； - 外壳是 Next.js App Router + Tailwind，UI 改起来顺手；Braintrust 负责观测、Plausible 负责访问统计，都是可选插拔。
三、官方界面预览
题图即官方仓库 README 内嵌的首页 og-image：顶部是 LlamaCoder
品牌标识（</> 图标 + LlamaCoder 字样），中间大字"Turn
your idea into an app"，下方是一个大输入框，占位文案为"Build me a
budgeting app…"；输入框左下角可选择模型（Llama 3.1
405B）与生成质量档位（Low quality
[faster]），右下角是发送按钮，整页右上角标注"Powered by
together.ai"。这就是你本地 npm run dev
启动后会看到的主界面形态——官方在线站 llamacoder.io
也是同一套前端，区别只是它用的是官方申请好的 Together Key
与托管数据库，你自建时换成自己的即可。
四、官方链接汇总
| 资源 | 地址 |
|---|---|
| GitHub 仓库 | https://github.com/Nutlope/llamacoder |
| 在线站点 | https://www.llamacoder.io |
| Together AI 控制台（申请 API Key） | https://api.together.ai |
| Neon 无服务器 PostgreSQL（官方推荐） | https://neon.tech |
| 贡献指南 CONTRIBUTING.md | https://github.com/Nutlope/llamacoder/blob/main/CONTRIBUTING.md |
五、前置要求
- Node.js 与 npm：项目基于 Next.js 16.3.8、React
19.2.9，需自行安装受支持的 Node.js LTS 版本与 npm（具体 Node
版本要求以仓库最新
package.json的 engines 字段为准，README 未硬编码）； - Together AI 账号与 API Key：项目默认调用 Together AI 的 LLM 推理，必须先在 Together 控制台申请一个 API Key；
- PostgreSQL 数据库连接串：官方 README 推荐用 Neon
开通一个 Serverless PostgreSQL，并拿到 Prisma
格式的连接串（
DATABASE_URL）； - S3 兼容对象存储（截图功能需要）：用于上传生成结果截图，需要 Access Key / Secret / Bucket / Region 四要素；
- Braintrust API Key（可选）：仅用于观测统计，不填不影响主流程；
- 网络：esbuild-wasm 从 esm.sh 加载浏览器依赖，预览沙盒需能访问相关 CDN。
六、安装部署（命令照抄）
官方 README 的部署三步：
# 1. 克隆仓库
git clone https://github.com/Nutlope/llamacoder
cd llamacoder在项目根目录新建 .env 文件，按下一节填好环境变量后：
# 2. 安装依赖
npm install
# 3. 本地启动开发服务器
npm run dev启动后按终端输出访问本地地址（Next.js 默认
http://localhost:3000，如端口被占用会自动顺延到
3001、3002……）。
七、配置项说明（.env 逐个讲）
| 环境变量 | 是否必填 | 说明 |
|---|---|---|
TOGETHER_API_KEY |
必填 | Together AI 的 API Key，负责实际的代码生成推理；没有它应用无法生成应用 |
DATABASE_URL |
必填 | PostgreSQL 连接串，官方推荐用 Neon 开通后粘贴 Prisma 格式连接串 |
BRAINTRUST_API_KEY |
可选 | Braintrust 观测平台 Key，用于记录模型调用，不填则不观测 |
S3_UPLOAD_KEY |
截图功能需要 | S3 兼容对象存储的 Access Key |
S3_UPLOAD_SECRET |
截图功能需要 | S3 兼容对象存储的 Secret Key |
S3_UPLOAD_BUCKET |
截图功能需要 | 桶名 |
S3_UPLOAD_REGION |
截图功能需要 | 桶所在区域 |
IMAGE_UPLOAD_TOKEN_SECRET |
截图功能需要 | 一个独立随机串，官方示例为
openssl rand -base64 32，且必须与
S3_UPLOAD_SECRET 不同 |
官方特别说明：截图上传只在约 30 分钟内有用（校验图片 token 的
TTL），建议给 next-s3-uploads/uploads/ 路径配一个 1
天过期的生命周期规则；如果 S3 凭证允许
s3:DeleteObject，未通过校验的上传会被立刻删除。上传器按"原样使用现有桶"的方式工作，不需要你额外建目录。
八、使用流程
- 本地
npm run dev，在浏览器打开终端给出的本地地址； - 在输入框用自然语言描述想要的小应用（示例占位："Build me a budgeting app…"）；
- 左下角可选模型档位（默认 Llama 3.1 405B）与生成质量（Low quality [faster] 更快、更省额度）；
- 点击右下角发送按钮，等待模型生成代码；
- 在右侧沙盒 iframe 中直接预览运行结果，依赖会经 esm.sh 在浏览器里拉取并由 esbuild-wasm 即时打包；
- 继续在对话框里提修改意见（"把按钮改成蓝色""加一个删除确认"），让模型迭代代码，直到满意；
- 需要留存时用截图上传功能把结果存到自己的 S3 桶。
想换成本地模型？README 默认链路是 Together 云端 API。如果你想完全离线、用自己的显卡跑，可以把发起推理的那一段改造成指向本地 Ollama / vLLM 等 OpenAI 兼容接口（改
baseURL与模型名即可），数据库与截图上传部分不受影响；这属于二次开发，官方 README 未提供现成开关，改完请自行测试。
九、常用运维 / 更新命令
# 拉取官方最新代码
git pull
# 依赖有变动后重新安装
npm install
# 本地重启开发服务器（Ctrl+C 后）
npm run dev
# 生成生产构建（自行部署时使用，具体脚本以 package.json 为准）
npm run build升级前建议先备份
.env，并在git pull后对照官方 README 确认是否新增或变更了环境变量；生产部署时同样需要配齐DATABASE_URL与各项 Key，不能只把静态文件丢上去。
十、常见故障排查
| 现象 | 原因与处理 |
|---|---|
| 生成时报 401 / 403 | TOGETHER_API_KEY 未填、填错或额度用完，去 Together
控制台核对 Key 与余额 |
| 启动时报数据库连接失败 | DATABASE_URL 不正确或 Neon
库未唤醒，复制完整连接串、确认库已开通（Neon 休眠后首次连接会稍慢） |
| 截图上传报错 | S3 四个变量与 IMAGE_UPLOAD_TOKEN_SECRET 未配齐，注意
token secret 要独立随机且不等于 S3 secret |
npm install 失败 |
网络或 Node 版本不兼容，切换到受支持的 Node LTS 版本后重装 |
| 预览区白屏 / 依赖加载不出 | esbuild-wasm 与 esm.sh 需联网，确认网络可访问对应 CDN，或检查代理设置 |
| 端口被占 | Next.js 自动换端口，看终端输出的实际地址即可，不用手动改 |
| 生成代码跑不起来 | 模型偶尔会写出有问题的依赖或语法，直接在对话框里让它修复，或手动改预览代码 |
| 改了代码不生效 | 确认改的是仓库源码并已重启
npm run dev；浏览器预览里手动改的代码刷新即丢失，要持久化得改工程源码 |
十一、风险与责任使用声明
- 本文命令、环境变量、版本号（Next.js 16.3.8 / React 19.2.9 / package 0.1.0）均来自官方 README 与 package.json，不构成对任何第三方服务可用性、费用的担保；
- Together AI、Neon、S3、Braintrust 均为外部付费/配额服务，注册与产生的费用由你自行承担，请留意用量与账单，尤其是大模型按 token 计费；
- 生成的代码由大模型产出，可能存在 bug、不安全写法、过期依赖或许可证问题，上线前务必自行审阅与测试，不要直接把生成代码用于生产或公网暴露；
- 项目以 MIT 许可证发布，按"AS IS"提供，使用风险自负；本文不托管、不代理该项目，也不对替换为其他模型后的行为负责。