诗词明信片集 - 开发与部署文档

本项目是一个用于生成并分享带拼音的精美古诗词卡片（明信片）的 Web 应用程序。内置了《唐诗三百首》和《诗韵书香》等丰富的古诗文库，支持卡片排版微调、自定义水墨山水写意底纹、导出精美 PNG 图片并支持高保真打印。

• 框架: React 19 + TypeScript 5
• 构建工具: Vite 6 (配置了极速打包、摇树优化)
• 样式: Tailwind CSS v4 (采用现代化 @import "tailwindcss"; 导入机制)
• 图片生成: html-to-image (将 DOM 树高保真转换为 PNG)
• 拼音引擎: pinyin-pro (精准的高音多音字拼音转换)
• 动画: motion (首屏及卡片切换的细腻过渡)
• 图标: lucide-react (现代化精美图标库)

在本地环境中开始开发或二次扩展本应用，只需以下几步：

确保本地电脑已安装 Node.js (建议版本 >= 18.0.0)。

在项目根目录下，使用终端运行以下命令安装项目包依赖：

npm install

运行以下命令启动支持热重载（HMR）的本地开发服务：

npm run dev

启动成功后，在浏览器中打开命令行提示的地址（通常为 http://localhost:3000 或 http://localhost:5173）即可预览和开发。

在应用需要上线或部署时，对项目代码进行生产环境构建：

npm run build

打包完成后，所有的静态资源文件（HTML、CSS、JavaScript、图片）会被编译并保存在项目根目录下的 dist/ 文件夹中。

针对您关心的**“是否可以直接在本地通过浏览器双击 index.html 访问，无需启动本地服务器运行”**：

• 原因：现代前端应用（包括由 Vite、React 打包的程序）在生成编译后采用的是 ES 模块化导入（ES Modules）。出于安全沙箱策略（CORS 限制），现代浏览器（如 Chrome、Safari、Edge）严格禁止通过 file:// 协议（本地路径）直接加载 ES 模块。若直接双击页面，控制台会抛出类似 Access to script at '...' from origin 'null' has been blocked by CORS policy 的错误。
• 图片导出限制：应用内的“导出卡片图片”功能依赖于读取 DOM 中的样式与图片，如果在 file:// 下运行，会导致 canvas 跨域限制，无法成功生成和下载。

如果您想在本地最省事地运行，无需搭建服务器：

1. VS Code Live Server (可视化、无代码) 如果您平时使用 VS Code 编辑器，只需安装 Live Server 插件。在 dist/ 目录下右键点击 index.html 并选择 "Open with Live Server"，它便会自动在本地以最轻量的方式拉起一个页面，无需终端配置。
2. 使用系统内置的一行指令 (无需额外安装) 在包含 dist/ 的文件夹下打开终端，运行任何您电脑已有的环境即可：
   • Node.js 环境 (推荐)：直接在终端运行静态服务容器

     npx serve dist

   • Python 环境：

     python -m http.server 8000 --directory dist

   • MacOS / PHP 环境：

     php -S localhost:8000 -t dist

现代 Web 开发中最提倡将此类“无状态纯前端应用”托管在全球 CDN / 静态托管平台上，这些平台均提供永久免费额度且部署极度简便：

1. Vercel / Netlify / Cloudflare Pages (极简零配置)

   • 流程：将您的代码提交至 GitHub。
   • 操作：登录 Vercel 或 Netlify，关联您的 GitHub 账号，选择该项目仓库，平台会自动识别为 "Vite + React" 应用。
   • 运行：点击 Deploy。平台会在 1 分钟内自动完成打包、部署，并分配一个带 HTTPS 的免费自定义域名给你。每次在 GitHub 上提交代码，它们还会自动更新部署。

2. GitHub Pages (免注册集成发布) 如果您希望直接使用自己的 GitHub 仓库自带的免费静态托管服务，可以选择 GitHub Pages。由于 GitHub Pages 默认的 URL 格式为 https://<用户名>.github.io/<仓库名>/，因此部署时需要进行一些路径适配。

   以下是最推荐的 依靠 GitHub Actions 自动构建与部署 的配置步骤（无需本地手动打包提交 dist）：

   第一步：修改 Vite 基础路径

   1. 打开根目录下的 vite.config.ts 文件。
   2. 在 defineConfig 配置中，添加 base 属性。将其值设置为您的 GitHub 仓库名称（前后带有斜杠），例如：

      export default defineConfig(() => {
        return {
          base: '/您的GitHub仓库名称/', // ⚠️注意：前后都有斜杠，例如 '/poetry-postcard/'
          plugins: [react(), tailwindcss()],
          // ...其他配置
        };
      });

      注：如果您直接将该应用部署在个人专属二级域名根目录下（如 https://<用户名>.github.io/），则 base 应设为 '/'。

   第二步：添加自动化构建工作流 (GitHub Actions)

   在项目根目录下，创建 .github/workflows/deploy.yml 文件，并写入以下自动化发布脚本：

   name: Deploy GitHub Pages
   
   on:
     push:
       branches:
         - main  # 或者是 your-default-branch 名称（例如 master）
   
   permissions:
     contents: write
     pages: write
     id-token: write
   
   jobs:
     deploy:
       runs-on: ubuntu-latest
       steps:
         - name: Checkout
           uses: actions/checkout@v4
   
         - name: Setup Node.js
           uses: actions/setup-node@v4
           with:
             node-version: 20
             cache: 'npm'
   
         - name: Install dependencies
           run: npm install
   
         - name: Build Application
           run: npm run build
   
         - name: Deploy to GitHub Pages
           uses: peaceiris/actions-gh-pages@v3
           with:
             github_token: ${{ secrets.GITHUB_TOKEN }}
             publish_dir: ./dist

   第三步：在 GitHub 仓库中开启设置并部署

   1. 将代码提交并推送（Push）到您的 GitHub 仓库。
   2. 在浏览器中打开您的 GitHub 仓库页面，点击右上角的 Settings (设置)。
   3. 在左侧导航栏中找到并点击 Pages (页面)。
   4. 在 Build and deployment (构建和部署) 区域下的 Source (来源) 选择：
      • 选项：Deploy from a branch。
      • 分支（Branch）选择刚刚由 Actions 自动创建的 gh-pages 分支，目录选择 / (root)。
   5. 点击 Save (保存)。稍等 1-2 分钟，页面上方就会显示形如 https://<用户名>.github.io/<仓库名>/ 的专属在线访问链接！

本项目支持完整的 Server-side 或 Client-side 容器部署。

• 一键发布：您可以通过 AI Studio 右上角的分享/部署工作流一键直接部署到托管平台。平台将在后台为您动态构建，并在全球高可用的云上自动分配免费域名并持续运行。