本文档记录了在 1Panel 环境下，使用 Docker 容器构建并部署 Astro 项目（以 astro-theme-pure 为例）的完整过程。
目录#
- 环境准备
- 创建静态网站与上传源码
- 创建 Node 运行环境容器
- 安装依赖
- 修改构建配置为静态模式
- 修复远程头像域名问题
- 构建项目
- 修改网站运行目录为 dist
- 配置 HTTPS（如果在第一步未完成）
- 后续更新流程
- （可选）本地开发调试
- 常见问题
环境准备#
- 已安装 1Panel 的 Linux 服务器。
- 域名解析：建议提前在域名服务商处将
timingme.com和www.timingme.com解析到你的服务器 IP。 - 已在 1Panel“应用商店”中安装并启动 OpenResty。
创建静态网站与上传源码#
-
打开 1Panel 左侧菜单 → “网站” → “创建网站”。
-
选择 “静态网站”。
-
填写信息：
- 域名配置：
- 在“域名”一栏，点击 “批量编辑” 按钮。
- 在弹出的文本框中输入两个域名（顺序不限）： text timingme.com www.timingme.com ↗
- 注意：1Panel 会根据你输入的第一个域名自动生成项目目录。
- 如果
timingme.com在第一行，目录为/opt/1panel/www/sites/timingme.com/index。 - 如果
www.timingme.com在第一行，目录为/opt/1panel/www/sites/www.timingme.com/index。 - 顺序均可，请记下页面下方显示的“根目录”路径，后续步骤需保持一致。
- 如果
- 备注：如“Astro Blog”。
- 根目录：保持默认（1Panel 会根据第一个域名自动填入），请记下此路径。
- 启用 HTTPS（可选但推荐）：
- 如果你的域名已解析生效，且服务器开放了 80/443 端口，你可以直接勾选此项，并选择“Let’s Encrypt”来自动申请证书。
- 如果你已有证书（如购买的证书），可勾选后选择“已有证书”并上传。
- 注：如果暂时不确定，可以不勾选，等待网站创建完成后，在“网站设置”中再申请也可以。
- 域名配置：
-
点击“确认”。
-
打开“网站”列表，找到刚创建的网站，点击“网站目录”下的文件夹图标，进入
index目录。 -
在“文件”界面：
- 点击“上传”，将主题源码压缩包上传到
index目录。 - 选中压缩包，点击“解压”。
- 确保解压后的项目文件直接位于
index目录下（能直接看到package.json、astro.config.ts等）。
- 点击“上传”，将主题源码压缩包上传到
创建 Node 运行环境容器#
使用官方 Node 镜像作为构建环境，并设置启动命令让容器保持常驻。
- 打开 1Panel 左侧菜单 → “网站” → “运行环境”。
- 选择 “Node” → “创建运行环境”。
- 填写配置：
- 环境名称：自定义，如
astro-node。 - Node 版本：选择最新 LTS（如 22）。
- 项目目录：填写你在上一步“创建静态网站”时看到的根目录路径。
- 例如：
/opt/1panel/www/sites/timingme.com/index（或其他实际生成的路径）。 - 关键点：此处必须与静态网站的实际代码目录完全一致，否则容器无法读取源码。
- 例如：
- 端口映射：填写
4321:4321（用于开发调试，生产环境构建不需要）。 - 启动命令（关键步骤）：
- 选择“自定义启动命令”。
- 填入：
tail -f /dev/null - 解释：Astro 是静态构建，不需要常驻的 Node 服务。如果选择默认的
npm start等命令，容器启动后会找不到服务入口并自动退出，导致你无法进入终端敲命令。tail -f /dev/null是一个“占位”命令，能让容器保持**一直运行（Running）**的状态，这样你随时都可以通过 1Panel 进入容器终端去执行npm run build。此命令资源占用极低，不会影响服务器性能。
- 环境名称：自定义，如
- 点击“确认”，等待容器创建并启动。
- 确认容器状态为“运行中”。
安装依赖#
为了保证在不同服务器架构下（如从 Mac 到 Linux）的兼容性，建议进行全新安装。
- 打开 1Panel 左侧菜单 → “容器”。
- 在容器列表中找到刚创建的 Node 环境容器，点击右侧 “终端”。
- 确认目录：进入终端后，通常会自动处于
/app目录。你可以输入pwd确认。如果不在，请执行cd /app。 - 依次执行以下命令：
bash rm -rf node_modules package-lock.json npm install
解释：删除旧依赖（可能包含不兼容的二进制文件），然后在当前容器环境中重新编译安装。
💡 提示：为什么要删除
package-lock.json？package-lock.json记录了本地环境的精确依赖版本。在 Docker 容器中直接复用本地锁文件可能会导致二进制文件（如 Sharp）因系统架构不同（如 Mac vs Linux）而加载失败。删除它会强制 npm 根据package.json在当前容器环境中重新生成锁文件，确保兼容性。
-
安装成功的标志： 执行完毕后，如果看到类似以下输出（包含
added ... packages和audited ... packages），即表示安装成功：text added 685 packages, and audited 686 packages in 4m
283 packages are looking for funding run npm fund for details
6 vulnerabilities (2 low, 4 high)
💡 未完待续···